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FOREWORD 


This  document  was  developed  for  the  U.S.  Departme.it  of  Agriculture  Soil  Conservation  Service 
under  reimbursable  Project  R-FED-SCS,  “Office  of  GRASS  Integration”;  Work  Unit  VH1.  The  SCS 
technical  monitor  was  Dr.  Richard  Liston,  USDA  SCS-CGIS. 

This  work  was  performed  by  the  Environmental  Division  (EN)  of  the  U.S.  Army  Construction 
Engineering  Research  Laboratory  (USACERL).  The  USACERL  principal  investigator  was  Marjorie 
Larson.  Dr.  Edward  Novak  is  Acting  Chief,  USACERL-EN.  William  D.  Goran  is  team  leader  of  the 
Spatial  Analysis  Systems  (SAS)  Team.  The  USACERL  technical  editor  was  William  J.  Wolfe. 
Information  Management  Office. 

In  addition  to  the  authors  cited  on  the  cover,  this  manual  was  a  product  of  the  efforts  of  many 
contributing  authors:  Jacinda  Barbehenn,  Deborah  Brinegar,  Kurt  Buehlcr,  Joo  Joo  Chia,  Chuck 
Ehlschlaeger,  Jean  Ezell,  David  Gerdes,  Andrew  Heekin,  Michael  Higgins,  Hewijin  Jiau,  Mark  Johnson, 
Marjorie  Larson,  Mary  Martin,  Jean  Messersmith,  Jan  Moorman,  Christine  Poulscn,  Melissa  Records, 
Marilyn  Ruiz,  Michael  O’Shea,  David  Stigberg,  Scott  Tweddalc,  L.  Van  Warren,  Scott  Wade,  and  Hong 
Zhuang  (USACERL);  Michael  Baba  and  David  Johnson  (DBA  Systems,  Inc.,  Fairfax,  VA);  Chris  Rewcrts 
and  Raghavan  Srinivasan  (Agricultural  Engineering  Department,  Purdue  University);  Antony  Awaida  and 
Kewan  Q.  Khawaja  (Intelligent  Engineering  Systems  Laboratory,  Massachusetts  Institute  of  Technology, 
Cambridge,  MA);  James  Hinthome  and  David  Satnik  (Central  Washington  University);  Dennis  Finch,  Tom 
Howard,  and  Bruce  Powell  (National  Park  Service);  James  Farley  (Arkansas  Archeological  Survey); 
Donald  Newcomb  (U.S.  Naval  Oceanographic  Office);  Greg  Kocrper  (USEPA  Environmental  Research 
Laboratory,  Oregon  State  University);  Chris  Emmerich  (Autometric,  Inc  );  Kenneth  Shepardson  (Spectrum 
Sciences  and  Software,  Inc.);  Ali  R.  Vali  (Space  Research  Center,  University  of  Texas,  Austin);  Dale 
White  (Pennsylvania  State  University);  Larry  Band  (University  of  Toronto);  P.W.  Carlson,  Paul  H. 
Fukuhara,  R.L.  Glenn,  M.L.  Holko,  and  Harold  Kane  (U.S.  Department  of  Agriculture  Soil  Conservation 
Service  [USDA  SCS]).  To  all  those  who  spent  many  hours  testing  this  software  prior  to  its  release, 
special  thanks  are  also  given. 

Special  recognition  is  also  given  to:  George  W.  Hagcman  (SOFTMAN  Enterprises,  Boulder,  CO); 
Daniel  S.  Cox  (In  Touch,  Atlanta,  GA).  Thanks  are  also  due  to  Dr.  A.V.  Hershey  (U.S.  National  Bureau 
of  Standards)  for  the  use  of  the  public  domain  version  of  the  Hershey  Fonts  in  the  program  d  fonts,  and 
to  Jeff  Poskanzer  for  the  use  of  the  Portable  Pix  Map  (PPM)  utilities. 

COL  Daniel  Waldo,  Jr.,  is  Commander  and  Director  of  USACERL,  and  Dr.  L.R.  Shaffer  is 
Technical  Director. 
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INTRODUCTION 


Background 

This  reference  manual  details  use  of  each  program  distributed  with  version  4.0  of  the  Geographic 
Resources  Analysis  Support  System  (GRASS),  a  public  domain  image  processing  and  geographic 
information  system  (GIS)  originally  developed  by  researchers  in  the  Environmental  Division  of  the  U.S. 
Army  Construction  Engineering  Research  Laboratories  in  Champaign,  IL.  The  GRASS  system  is  used 
to  input,  manipulate,  analyze,  and  output  geographic  data  by  users  in  both  military  and  nonmilitary,  public 
and  private  agencies,  based  in  North  America,  Europe,  and  other  parts  of  the  world. 

Although  most  GRASS  development  has  been  conducted  at  USACERL,  system  integration,  development, 
testing,  distribution,  training,  and  support  are  performed  by  numerous  publicly  and  privately  operated  sites 
throughout  the  world.  GRASS  version  4.0  implemented  significant  additions  and  modifications  to  system 
libraries  and  programming  code.  Mechanisms  are  needed  to  transfer  current  technology  and  information 
about  GRASS  to  user  and  development  sites. 

This  manual  explains  the  capabilities,  syntax,  and  use  of  current  GRASS  programs.  Chapters  are  ordered 
alphabetically,  by  program  name,  one  program  to  each  section.  Each  section  contains: 

•  the  program  name  and  a  short  description 

•  a  synopsis  of  files  associated  with  the  program 

•  a  full  description  of  the  program's  capabilities  and  uses 

•  a  summary  of  the  command-line  options  associated  with  the  program 

•  a  list  of  associated  or  related  programs 

•  a  list  of  program  authors. 

Each  section  may  optionally  include:  a  description  of  the  program'*  operation  in  “interactive  mode,”  and 
a  discussion  of  “bugs,”  program  limitations,  or  special  notes  of  potential  interest  to  GRASS  users. 

Throughout  this  manual,  program  inputs  to  be  explicitly  entered  by  the  user  are  printed  in  bold  text.  User- 
specified  inputs  (i.e.,  variables  set  by  the  user)  are  set  in  italic  type.  Boxed  text  shows  information  output 
to  the  user’s  terminal  screen. 


Scope 

This  document  details  the  use  of  GRASS  version  4.0  programs  released  in  July  1991.  Figures  and  facts 
about  GRASS  relate  to  the  4.0  and  previous  releases.  Some  elements  of  this  document  will  be  dated  and 
inaccurate  for  post-4.0  software  releases. 


Mode  of  Technology  Transfer 

GRASS  is  being  transferred  to  the  field  through  the  following  mechanisms:  training  programs,  hands-on 
experience,  a  user  support  center,  newsletters,  extensive  documentation,  institutional  structures  at  the  Army 
and  Interagency  levels,  communication  networks,  and  other  forums:  GRASS  source  code  can  be  obtained 
by  anonymous  ftp  from  moon.cecer.anny.mil.  Current  information  is  available  from  the  GRASS 
Information  Center  at  USACERL,  which  can  be  contacted  by  Phone:  217-373-7220;  Fax:  217-373-7222; 
or  e-mail:  grassbug@zorro.cecer.army.mil. 
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2  MAIN  PROGRAMS  AND  PROGRAMS  IN  ALPHA-TESTING 


GRASS,  a  product  of  the  U.S.  Army  Corps  of  Engineers  Construction  Engineering  Research  Laboratory 
(USACERL),  in  Champaign,  IL,  is  an  integrated  set  of  programs  designed  to  provide  digitizing,  image 
processing,  map  production,  and  geographic  information  system  capabilities  to  its  users.  Although  most 
GRASS  system  development  continues  to  be  conducted  by  the  Environmental  Division  of  USACERL, 
system  integration,  development,  testing,  distribution,  training,  and  support  are  performed  by  numerous 
publicly-  and  privately-operated  sites  throughout  the  world.  Other  agencies  have  also  written  programs 
for  distribution  with  GRASS. 

Whatever  their  origin,  all  programs  distributed  with  GRASS  4.0  undergo  scrutiny  and  testing  prior  to  their 
release.  This  chapter  describes  the  syntax  and  use  of  GRASS  4.0  programs  that  have  unr^rgone  (and 
survived)  alpha-and  beta-testing  (i.e.,  initial  testing  by  program  developers,  and  subsequent  testing  by  out- 
of-house  users).  These  programs  constitute  the  bulk  of  GRASS,  and  are  respectively  referred  to  in  the 
documentation  as  "Alpha  Programs"  and  "Main  Programs."  "Main  Programs,"  which  receive  both  alpha- 
and  beta-testing  prior  to  their  release  and  are  located  in  the  src  directory,  are  compiled  automatically 
during  general  GRASS  compilation.  "Alpha  Programs,"  which  receive  only  alpha-testing  prior  to  release 
and  are  located  in  the  src.alpha  directory,  must  be  compiled  separately  by  the  user.  The  GRASS 
Installation  Guide  distributed  with  GRASS  4.0  software  explains  the  compilation  procedure. 
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d.3d  GRASS  Reference  Manual  d3d 


NAME 

d.3d  -  Displays  three-dimensional  images  based  on  raster  map  layers. 

(GRASS  Display  Program) 

SYNOPSIS 

d3d 

d.3d  help 

did  [HOaj  map  name  elevation  name  [froBni_coordinate=^r,y,z] 

[to_coordinate=x,y,z]  [exaggeration  =value]  [lines  =value]  [field  =value\ 

[color ^name\  [b ox=name\ 

DESCRIPTION 

d.3d  displays  three-dimensional  graphic  images  based  on  GRASS  raster  map  layers.  The  user  identifies 
the  viewing  point,  the  line  of  sight,  a  vertical  exaggeration  factor,  the  viewing  angle  (field  of  view),  the 
frequency  and  color  of  vector  grid  lines  to  appear  in  the  display,  the  map  to  be  displayed  in  three 
dimensions,  and  the  map  whose  category  values  are  to  be  used  as  elevation  values  in  the  three- 
dimensional  image. 

The  program  will  be  run  non-interactively  if  the  user  specifies  all  needed  parameter  values  and  flag 
settings  on  the  command  line.  Alternately,  the  user  can  simply  type  d3d  on  the  command  line;  in  this 
case,  the  program  will  prompt  the  user  for  parameter  values  and  flag  settings  using  the  standard 
interface  described  in  the  manual  entry  for  parser. 

Three-dimensional  images  can  also  be  generated  through  the  GRASS  d.display  program. 

COMMAND  LINE  OPTIONS 
Flags: 

-I  Display  lines  only,  without  displaying  the  raster  base  map. 

-0  Show  zero  elevations. 

-a  Each  grid-cell  is  rendered  using  four  elevation  coordinates:  one  for  each  comer. 

By  default,  each  comer  takes  the  value  of  the  gritEcell  to  the  lower  right.  With 
the  a  option  each  comer  is  calculated  to  be  an  average  of  the  four  bordering  cel 
elevation  values. 

Parameters: 

map  name  The  raster  map  layer  used  to  generate  the  color  shown  in  the  three  dimensional 

output  (i.e.,  the  map  whose  x  and  y  values  will  be  displayed,  using  the  z  values 
present  in  the  elevation  map  layer.) 

elevation  natne  The  raster  map  used  to  generate  the  texture  in  the  three-dimensional  image  (ie., 
the  map  whose  category  values  will  become  the  elevation  values  in  the  three 
dimensional  map  displayed).  This  need  not  be  an  elevation  map  layer,  although 
elevation  is  commonly  used. 

Default:  elevation 

from  coordinate  =x,y,z 

Coordinates  of  the  viewing  point,  given  as:  northing,easting, elevation.  The 
default  from_coordinate  value  is  appropriate  for  the  spearfish  sample  data  set. 
Default:  Calculated  at  run-time  just  south-west  of  the  south-west  comer. 

to  coordinate  ~^x,y,z 

Gxirdi nates  of  center  of  view,  given  as:  northing, easting, elevation.  The 
default  to_coordinate  value  is  appropriate  for  the  spearfish  sample  data  set. 
Default:  Calculated  at  run  time  as  the  center  of  the  image 
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exaggeration  =value 

Vertical  exaggeration  factor.  This  value  is  multiplied  by  the  "elevation"  values 
(category  values)  in  the  elevation  map  layer.  As  the  vertical  coordinates  are 
exaggerated,  the  elevation  (z)  value  of  the  center  of  view  (the  lo_coordmate) 
should  be  increased. 

Default:  2.0 

North-south  and  east-west  trending  lines  can  be  drawn  on  the  three-dimensional 
image  output,  to  enhance  the  three-dimensional  effect.  The  lines  value  specifies 
the  number  of  rows  and  columns  to  skip  between  lines.  0  means  "display  no 
lines."  Lines  will  be  drawn  in  the  color  stated.  The  user  can  elect  to  rally 
display  these  lines,  without  displaying  the  map,  by  setting  the  -1  flag. 

Default:  1 

The  field  of  view  (viewing  angle)  in  the  image,  stated  in  degrees. 

Default:  30 

Color  of  vector  lines  drawn  on  the  output. 

Options:  color,  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  Mack 
Default:  gray 

The  resulting  three-dimensional  image  is  drawn  in  the  active  frame  on  the  graphics  monitor.  The  user 
should  select  and  erase  the  full  graphics  monitor  frame  before  running  d.3d  to  prepare  the  screen  for 
graphics.  Refer  to  the  GRASS  program  3d.view  jsh  for  a  demonstration  of  the  d.3d  program. 

INTERACTIVE  MODE 

The  interactive  mode  prompts  fra  the  raster  map  to  be  rendered,  the  raster  map  to  be  queried  for 
elevation  information,  and  an  optionally  saved  set  of  saved  viewing  parameters.  The  user  is  then 
presented  with  a  form  in  which  the  options  can  be  modified. 

B  is  suggested  that  the  following  procedure  be  used  to  efficiently  find  the  correct  viewing  parameters. 
Start  with  a  gross  grid  (by  default,  a  resolution  is  chosen  that  limits  the  total  number  of  rows  and 
columns),  display  lines  rally,  set  line  colors  to  "color"  (lines  take  their  color  from  the  map),  set  the  box 
color  to  something  other  than  "none",  and  use  the  default  viewing  coordinates.  Experiment  with  the 
viewing  coordinates  until  the  map  is  positioned  in  a  desirable  configuration.  When  the  map  is  lined  up 
correctly,  set  die  display  resolution  as  low  as  you  like  fra  a  final  image. 


lines  =value 

field  =value 
color  name 


BUGS 

Several  additions  to  this  program  have  been  suggested.  These  include  the  following: 

1)  Border  the  image  with  a  visually  appealing  curtain. 

2)  Add  x,y,z  coordinates  and  scale  information  to  the  displayed  three-dimensional  image. 

3)  Provide  a  graphic-oriented  user  interface  for  identifying  viewing  parameters. 

4)  Display  output  more  quickly  by  doing  mathematics  in  integers. 

5)  Add  the  option  of  plotting  vector  map  layers. 

SFE  ALSO 

3d.viewjsh,  d. display,  d.erase,  d.frame,  and  parser 

AUTHOR 

Janies  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.ask  -  Prompts  the  user  to  select  a  GRASS  data  base  file  from  among  files  displayed  in  a  menu  on 
the  graphics  monitor. 

(GRASS  File  Management  Program) 

SYNOPSIS 

d.ask  help 

d.ask  element  =name, description  [  prompt  =" message"] 

DESCRIPTION 

d.ask  is  designed  for  shell  scripts  that  need  to  prompt  the  user  for  the  name  of  a  data  base  file  in  the 
user’s  current  GRASS  mapset  search  path.  After  d.ask  is  invoked  with  needed  parameters,  the  mouse 
becomes  active  and  a  menu  containing  files  of  the  specified  element  type  is  displayed  on  the  user’s 
graphics  monitor.  The  user  is  prompted  by  the  prompt  "message”  to  select  one  of  the  listed  file  names 
with  the  mouse.  Specifically,  the  query  that  appears  to  the  user  takes  the  form: 

Double  dick  on  the  prompt  " message ” 

Double  dick  here  to  cancel 

(A  list  of  files  of  the  specified  element  type  from  each  of  the  mapsets 
listed  in  the  user’s  mapset  search  path  is  also  displayed.) 

After  the  user  responds,  the  mouse  is  deactivated  and  the  displayed  menu  is  erased  from  the  screen 
(leaving  any  underlying  materials  on  display  intact).  Three  lines  are  written  to  standard  output  (the 
user’ s  terminal  screen): 

name  =file_name 
mapset  -mapset  name 
fullname/i/e  _name@mapset _name 

Parameters: 

element  =name, description 

Name  of  a  GRASS  data  base  element,  followed  by  a  one  word  description  of 
the  element.  GRASS  data  base  elements  are  mapset  subdirectories;  these 
include:  bdlg,  cats,  cell,  celLmisc,  cellhd,  coir,  cdr2,  dig,  dig_ascii,  dig_att, 
dig_cats,  dig_plus,  dig,  group,  hist,  icons,  noise,  paint,  site_lists,  and  windows. 
I  he  description  will  Ire  used  to  display  an  error  message  to  the  screen  if  no 
files  of  the  named  element  type  exist  in  the  user’s  mapset  search  path.  The 
prompt  "message”  will  appear  in  the  popup  menu  displayed  on  the  user’s 
graphics  monitor.  The  files  listed  in  the  menu  will  be  of  the  specified  element 
type,  anti  exist  in  mapsets  listed  in  the  user’s  current  mapset  search  path. 

prompt  =”  message"  A  brief  message  with  which  the  user  will  be  prompted.  If  this  message 

contains  more  than  one  word,  it  should  be  enclosed  within  double  quotes  ("”). 
It  is  a  non- selectable  message  displayed  in  the  menu  bar  of  a  popup  menu. 
Selectable  items  in  the  displayed  menu  include  a  caned  option  and  any  of  the 
files  in  the  mapset  sulxlirectory  name  in  the  user’s  mapset  search  path. 

EXAMPLE 

(iiven  the  following  input, 

d.ask  element  =cell,raster  prompt -"raster  map  layer  to  be  used” 

d.ask  will  prompt  the  user  to  select  a  raster  (cell)  tile  from  among  those  listed  in  the  "cell"  directories 
of  the  limpets  listed  in  his  current  mapset  search  pith.  A  pip  up  menu  will  be  vlisplayed  on  the  user’s 
graphics  monitor,  containing  the  (irompt: 

Double  click  on  the  raster  map  layer  to  be  used 

Double  click  here  to  cancel 
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OUTPUT 

If  the  user  selects  a  file  name  from  the  displayed  menu,  d.ask  writes  three  lines  to  standard  output: 

name  —file_name 

mapset  =mapset_name 

full  name  =file_name@mapset_name 

The  output  is  in  the  form  of  /bin/sh  commands  to  set  the  variable  name  to  the  file  name  specified  by 
the  user  (of  the  element  type  requested  by  d.ask),  mapset  to  the  GRASS  mapset  in  which  this  file 
resides,  and  full  name  to  the  name  of  the  file  and  its  mapset. 

If  the  user  elects  not  to  select  a  file  but  instead  chooses  the  "Double  click  here  to  cancel"  option,  the 
mouse  will  be  deactivated  and  no  variable  assignments  will  be  returned  to  standard  output. 

If  no  files  of  the  specified  element  type  are  found  in  the  user’s  current  mapset  search  path,  the  mouse  is 
activated  and  the  following  message  is  displayed  on  the  user’s  graphics  monitor: 

No  element  description  files  found 
Click  here  to  continue 

NOTES 

Parameter  values  (the  element  name  and  description,  and  prompt  message)  cannot  be  supplied  to  d.ask 
interactively;  they  must  be  suoplied  on  the  command  line  or  from  a  file. 

SEE  ALSO 

g.ask,  g.filena.Tte,  g.findfile,  g  gisenv,  g.mapsets 

BUGS 

This  program  calls  other  GRASS  programs  that  may  generate  confusing  error  messages.  Example:  an 
error  message  from  the  program  d.mcnu  will  appear  if  a  nonexistent  map  element  is  chosen. 

AUTHOR 

Michael  Shapiro,  U.S.  Anny  Constnietion  Engineering  Research  laboratory 
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NAME 

t Lcoiormode  -  Allows  the  user  to  establish  whether  a  map  will  be  displayed  using  its  own  color  table 
or  the  fixed  color  table  of  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.coiormode 
d.coiormode  help 
d.coiormode  mode  =name 

DESCRIPTION 

(Lcoiormode  establishes  what  color  table  will  be  used  to  display  maps  to  the  graphics  monitor. 

Parameters: 

mode  name  Options:  fixed  or  float 

Each  time  a  new  raster  map  layer  is  drawn  on  the  screen,  a  color  table  associated  with  that  map  is 
loaded  into  the  graphics  display  monitor.  The  command  dxoiormode  mode  =fixed  requests  that  the 
monitor’s  color  look  up  table  be  fixed  (i.e.,  static).  The  effect  is  that  colors  drawn  on  the  screen  by 
graphics  calls  will  not  change  when  subsequent  maps  are  drawn  to  the  screen.  When  the  fixed  option  is 
used,  the  colors  in  the  map’s  color  table  are  mapped  to  the  nearest  colors  available  in  the  monitor’s 
fixed  color  table.  When  the  float  option  is  used,  the  map’s  color  table  is  loaded  directly  into  the 
monitor’s  color  look-up  table. 

There  are  advantages  to  using  each  color  display  mode.  The  d. display  and  (Lectors  programs  allow 
the  user  to  interactively  modify  the  color  tables  of  maps  displayed  to  the  graphics  monitor.  This  is 
done  by  allowing  the  user  to  directly  modify  the  monitor’s  color  look-up  table.  Hence,  to  accommodate 
this  option  in  d.display  and  d.colors,  the  dxoiormode  mode  =  float  option  is  chosen.  However,  this 
option  has  the  sometimes  undesirable  effect  erf  changing  the  colors  in  which  other  maps  are 
subsequently  displayed  to  the  graphics  monitor  (although  it  does  not  actually  change  the  color  tables 
erf  these  latter  maps).  The  float  colormode  is  therefore  best  used  when  the  user  wishes  to  interactively 
change  a  map’s  color  table,  or  when  the  user  wishes  to  display  one  or  more  maps  having  the  same 
color  table.  The  fixed  option  allows  any  number  of  maps  to  be  displayed  to  the  screen,  where  each 
map  uses  different  colors,  but  all  use  the  same  fixed  color  look-up  table.  You  cannot  toggle  a  map’s 
color  table  when  nuuiing  in  fixed  mode. 

This  program  will  be  run  non-interactively  if  the  user  specifies  the  color  mode  on  die  command  line 
(eg.,  by  typing  d.coiormode  mode  =- fixed  or  dxoiormode  mode  float).  Alternately,  if  the  user 
simply  types  dxoiormode  on  the  command  line,  the  program  will  prompt  the  user  for  the  color  mode 
using  the  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

NOTES 

Some  devices  support  only  a  fixed  color  look-up;  eg.,  ink-jet  printers,  plotters,  and  the  AT&T  6300 
(running  a  DER  board),  lhe  number  of  color  categories  capable  of  being  displayed  is  also  device- 
dependent;  if  your  colors  fall  outside  this  range  when  in  float  mode,  they  may  not  lie  displayed  in  the 
colors  indicated  in  the  map’s  color  table  file.  However,  the  color  table  files  themselves  will  accurately 
represent  the  user’s  changes. 

Color  table  files  associated  with  raster  map  layers  are  stored  in  the  user’s  current  mapset  under  the  coir 
and  colr2  directories. 

BUGS 

It  is  strongly  recommended  that  tlie  user  erase  the  graphics  monitor  screen  (eg.,  Iw  nuuiing  d.erase) 
immediately  after  changing  the  mode  between  fixed  and  float. 
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SEE  ALSO 

i icoiors ,  (Lcolortable,  duiisplay,  tLerase,  d.rast,  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 


GRASS  4.0  (Summer  1991) 


U.S.  Armv  ( 1RI 


I 


cLcdors 


GRASS  Reference  Manual 


d.calors 


NAME 

dxoiors  -  Allows  the  user  to  interactively  change  the  color  table  of  a  raster  map  layer  displayed  an  the 
graphics  monitor. 

(GRASS  Duplay  Program) 

SYNOPSIS 

dxoiors 
dxoiors  help 
dxoiors  map=name 

DESCRIPTION 

A  color  table  file  associates  specific  colors  with  the  categories  of  a  raster  map  layer.  The  user  can 
change  these  map  category  color  assignments  (i.e.,  change  the  map’s  color  table)  interactively,  by  first 
displaying  the  raster  map  to  the  graphics  monitor  and  then  running  the  program  dxoiors.  If  you  have 
first  set  eLcolormode  to  "float"  before  displaying  the  map  to  the  graphics  monitor,  any  color  changes 
that  you  subsequently  make  while  in  d. colors  will  immediately  (and  interactively)  appear  on  the 
graphics  display.  Otherwise,  if  eLcolormode  is  "fixed,”  any  color  changes  made  using  dxoiors  will 
not  immediately  be  shewn  on  the  graphics  display;  however,  any  color  changes  saved  will  still  alter  the 
map’s  color  table  and  will  appear  next  time  the  raster  map  layer  is  redisplayed  (see  eLcolormode  and 
d. col  or  table).  Note  that  some  graphics  display  monitors  or  drivers  cannot  support  interactive  color 
change. 

The  user  must  first  display  the  relevant  raster  map  layer  to  the  active  frame  on  the  graphics  monitor 
(eg.,  using  d.rast  or  i Ldisplay )  before  running  dxoiors.  The  user  can  then  either  enter  the  name  of 
the  raster  map  layer  whose  color  table  is  to  be  changed  on  the  command  line  (eg.,  by  typing:  dxoiors 
map  =s«* Is),  or  type  dxoiors  without  program  arguments.  If  the  user  simply  types  dxoiors  without 
program  arguments  on  the  command  line,  dxoiors  will  ask  the  user  to  enter  the  name  of  an  existing 
raster  map  layer  using  the  standard  GRASS  interface  described  in  the  manual  entry  for  parser. 

In  either  case,  the  user  is  then  presented  with  the  d.colors  command  menu,  shown  below.  This  menu 
is  the  same  as  the  category  and  color  changing  portion  of  the  (Ldisplay  menu.  The  cLcolors 
commands  are  listed  beneath  the  Category  Pointer  Movement,  Color  Modification,  Replotting  Screen, 
and  Quitting  sections  below.  Commands  are  invoked  by  typing  in  the  angle- key  response  shown  to  the 
left  below.  (Longer  descriptions  of  these  commands  appear  to  the  right.)  Results  from  invoking  these 
commands  will  be  reflected  in  the  Category  and  Category  Number  sections  of  the  dxoiors  screen.  On 
the  dxoiors  screen  menu,  commands  appear  in  the  right  half  of  the  screen,  and  the  current  status  of 
categories  appears  in  the  left  half  of  the  screen. 

CATEGORIES 
0  No  Data 

1  (Category  1  description) 

2  (Category  2  description) 

CATEGORY  NUMBER: 

RED  0  0% 

GREEN  0  0% 

BLUE  0  0% 

Shift  Incr:  10  3% 

CATEGORY  POINTER  MOVEMENT 
D/d  dewn  (cats) 

UAi  up  (cats) 

COIjOR  MODIFICATIONS 
RA  RED 
G/g  GREEN 
B/b  BLUE 


Move  pointer  to  next  category 
Move  pointer  to  previous  category 

Increase/decrease  RED  intensity 
Incrcase/decrease  GREEN  intensity 
Increase/decrease  BLUE  intensity 
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\A  increment 
h  highlight 
+/-  shift  colors 
c  save  color 
t  toggle  talde 
RFPLOTnNG  SCRETN 
*  Replot  screen 
QUITTING 
Q  quit 


Increase/decrease  increment  (of  intensity  shift) 

Highlight  current  color 

Shift  entire  color  table  (up/down) 

Save  color  table 

Toggle  to  different  color  table 

Replots  the  screen 

Quits  program 


Changing  categories  -  The  keys  d,  D,  a,  and  U  are  used  to  move  to  a  different  category .  The  lower 
case  letters  mov  e  up,  u,  and  dow  n,  d,  the  category  list  one  category  at  a  time.  Ihe  upper  case  letters 
move  10  categories  at  a  time  for  fast  movement.  The  cursor  does  wrap  between  the  first  and  last 
categories.  The  current  category  is  noted  on  the  text  screen  with  an  arrow,  and  is  indicated  on  the 
graphics  screen  by  a  box  around  the  current  color. 


Changing  colors  -  Ihe  color  associated  with  the  current  category  can  be  changed  with  the  R,  r,  (I,  g, 
B,  and  b  keys.  The  upper  case  letters  increase  the  intensities  of  red  R,  green  G,  and  blue  B  for  the 
current  category  ;  the  lower  case  letters  decrease  the  intensities  of  these  same  colors  for  the  current 
category.  Video  devices  make  all  the  colors  of  the  spectrum  by  mixing  red.  green,  and  blue.  For  those 
accustomed  to  red,  yellow,  and  blue  being  the  primary  colors,  this  can  be  confusing.  For  starters, 
yellow  is  made  liy  mixing  red  and  green.  The  intensities  are  listed  on  the  text  screen  as  percentages. 

Keys  I  and  i  increase  and  decrease  the  percentage  change  tliat  each  key  stroke  of  one  of  the  color  keys 
(R,  r,  G,  g,  B,  b)  causes  in  its  respective  color.  The  increase  increment  is  initially  set  to  10'/o.  Thus, 
pressing  the  R  key  will  increase  the  red  component  of  the  current  category  by  10% 

Highlight  -  The  h  key  toggles  between  the  current  category  color  and  the  current  highlight  color.  This 
color  is  initially  black  but  can  be  modified  as  above  while  in  highlight  mode.  Blinking  can  be 
accomplished  by  repeatedly  striking  the  h  key.  When  changing  to  different  categories  using  the 
movement  keys  as  described  above,  while  in  highlight  mode  the  category  colors  will  lx-  always  left 
showing  their  actual  colors.  Only  one  category  is  highlighted  at  any  one  time. 

Saving  the  current  color  table  -  Pressing  the  c  key'  will  save  the  current  color  table  as  you  have 
modified  it.  This  table  will  then  be  used  next  time  you  display  or  paint  this  raster  map  layer. 

Qtlor  table  toggle  -  Different  types  of  color  tables  are  suitable  for  different  raster  map  lay  ers.  The  kev 
t  flips  between  the  following  color  tables:  red,  green,  blue  color  ramp;  gray  scale;  snuxtth  ch. urging 
color  wave;  random  colors;  and  the  saved  color  table. 

Grlor  table  shift  The  entire  table  is  shifted  up  and  down  asing  the  +and  -  keys. 

Gutting  the  d.colors  program  -  Pressing  the  Q  key  will  cause  you  to  quit  the  d.colors  program.  If 
colors  have  been  nxxlified  but  not  saved,  d.colors  will  ask: 

Colors  changed 

Save  the  changes?  (yAi) 

The  U'er  should  type  in  y  to  save  changes,  or  n  to  not  save  changes.  Ire  lore  quitting  the  program.  If 
the  user  types  n.  the  program  will  ask: 

Quit  anyway?  (yAi) 

NOTES 

To  see  map  color  changes  reflected  on  the  display  monitor  as  you  make  them,  you  must  put  tin  monitor 
in  float  color  m<xlc  before  nmning  d.colors.  It  is  ;dso  wise  to  erase  the  display  screen  alter  changing 
the  color  mode. 
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The  map  whose  color  table  is  to  be  altered  with  dxolors  must  already  be  on  d splay  in  the  active 
display  frame  on  the  graphics  monitor  before  eLcolors  is  run.  This  can  be  done  using  the  command 
dj-ast  map  name  (where  name  is  a  raster  map  layer  whose  color  table  the  user  wishes  to  alter). 

The  user  might  type  the  following  sequence  of  commands  to  interactively  change  the  colors  of  a  raster 
soils  map: 

d.colormode  mode  float 
d  .erase 

d.rast  map  soils 
d  .colors 

After  the  user  has  saved  any  color  changes  made  with  dxolors  and  exited  the  program,  the  user  could 
then  redisplay  the  soils  map  with  the  new  colors  by  typing: 

d.colormode  mode=fixed 
d.erase 

d.rast  map=soils 

Some  color  monitors  may  not  support  the  full  range  of  colors  required  to  display  all  of  the  map’s 
categories  listed  in  the  map’s  color  table.  However,  regardless  of  whether  the  user  can  see  the  color 
changes  the  user  is  effecting  to  a  map’s  color  table,  any  changes  to  a  map’s  color  table  made  with 
dxolors  that  are  saved  will  appear  in  the  map’s  color  table. 

Some  monitors  may  not  support  an  interactive  color  change  capability. 

SEE  ALSO 

dxolormode,  d.colortable,  d.display,  d.rast,  pxaiors,  r. colors,  and  parser 
AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.coiortable  -  To  display  the  color  table  associated  with  a  raster  map  layer. 
(GRASS  Display  Program) 

SYNOPSIS 

d.col or  table 
d.coiortable  help 

d.coiortable  map  =name  [color  =name\  [lines  =*>alue)  [cei*=value] 


DESCRIPTION 

The  GRASS  program  dxolortable  is  used  to  display  the  color  table  associated  with  a  raster  map  layer 
in  the  active  frame  on  the  graphics  monitor.  The  map  name  should  be  an  available  raster  map  layer  in 
the  user’s  current  mapset  search  path  and  location. 

Parameters; 

map  =name  Name  of  a  raster  map  layer  in  the  user’s  current  mapset  search  path  whose  color 

table  is  to  be  displayed. 

color  name  Color  erf  the  lines  separating  the  colors  of  the  color  table. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  white,  and  black. 
Default:  white 


lines  =value  Number  of  lines  to  appear  in  the  color  table. 

Options:  1  -  1000 

cols  =value  Number  of  columns  to  appear  in  the  colew  table. 

Options:  1  -  1000 


If  the  values  of  both  lines  and  cols  are  new  specified  by  the  user,  d.coiortable 
divides  the  active  frame  equally  among  the  number  of  categories  present  in  the 
named  raster  map  layer.  If  erne  option  is  specified,  the  other  is  automatically  set 
to  accomnxxlate  all  categories.  If  both  are  specified,  as  many  categories  as 
possible  are  displayed. 

The  user  can  specify  all  needed  parameters  on  the  command  line  using  the  form: 

d.colartable  map  name  [color  =name]  [lines  =value]  [cols-  va/ue] 

If  the  user  specifies  the  name  of  a  map  on  the  command  line  but  does  not  specify  the  values  of  other 
parameters,  parameter  default  values  will  be  used.  Alternately,  if  the  user  types  simply  dxolortable 
on  the  command  line  without  any  program  arguments,  the  program  will  prompt  the  user  for  parameter 
settings  using  the  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

EXAMPLE 

The  user  running  the  command: 

dxolortable  map  sotls  color  red  lines=l  cols  =3 

would  see  the  active  graphics  frame  divided  into  three  columns  extending  the  full  frame  height.  1  lie 
lines  dividing  the  color  table  associated  with  the  soils  map  would  Ire  displayed  in  red.  Ihc  user  would 
see,  at  most,  only  three  of  the  colors  from  the  soils  color  table  displayed  in  the  active  frame  (lxvause 
the  user  requested  that  this  frame  be  divided  into  three  sections). 

NOTES 

If  the  user  wishes  to  display  the  entire  color  table  associated  with  a  map,  the  user  should  either  stipulate 
a  number  erf  lines  (rows)  and  columns  (cols)  sufficient  to  accommrxlate  the  number  of  categories  in  the 
map’s  color  table,  or  fail  to  assign  values  to  one  or  both  of  lines  and/or  cols.  If  the  user  nuts 
dxolortable  using  the  default  number  of  lines  and  columns  (the  full  graphics  frame).  ;dl  categories 
from  the  map’s  color  table  will  be  displayed.  However,  if  the  user  requests  that  tlx-  color  table 
associated  with  a  map  that  has  ten  data  categories  lie  displayed  in  a  graphics  frame  with  only  three 
lines  (rows)  and  two  columns  (a  total  of  six  cells),  only  six  of  the  ten  map  categories  will  Iv  displayed. 
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The  user  should  run  the  command  dxotarmode  mode  =41  oat  before  running  (Lcolortablc ,  for 
accurate  display  of  the  map’s  color  table. 

The  user  should  run  the  GRASS  program  d.erase  between  runs  of  dxolortable  to  avoid  confusion. 

SEE  ALSO 

d.colormode,  dxolors,  d.display,  d.erase,  dxast  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.display  -  A  menu-driven,  highly  interactive  display  pregram  for  viewing  maps  and  producing  final 
map  products 

(GRASS  Display  Program) 

SYNOPSIS 

d.diq>iay 

DESCRIPTION 

The  GRASS  program  d.display  is  used  to  ilisplay  maps  on  a  graphics  monitor  and  prepare  final  map 
products  for  printing.  It  is  advisable  to  first  run  d.erase  before  each  run  of  d.display  to  prepare  the 
screen  for  graphics. 

Ater  invoking  the  command  d.display,  the  DISPI  AY  MAIN  MINI  '  appears  on  the  monitor.  Options 
in  this  and  subsequent  d.display  menus  are  selected  through  use  of  the  pointing  device  (mouse).  When 
the  mouse  cursor  is  ov  er  the  desired  menu  selection,  the  user  simply  presses  any  Ixitton  on  the  mouse. 

d.display  is  a  macro  that  allows  the  user  to  access  a  wide  range  of  GRASS  display  functions  in  a 
menu-driven  and  highly  interactive  environment.  Most  of  the  functions  accessible  through  d.display 
am  also  lie  run  independently  of  one  another  by  ntnning  the  GRASS  display  id.)  commands  listed  in 
the  SEE  ALSO  section,  below.  However,  in  many  cases,  these  other  d.  commands  give  the  user  greater 
flexibility  and  make  available  more  options  than  are  available  through  the  d.display  menus.  For 
example,  the  d.display  label  file  option  runs  the  d.label  command  using  defaults.  Users  running 
d.label  directly  from  the  command  line  have  the  choice  of  stipulating  specific  label  background  and 
text  colors,  as  well  as  text  sizes  and  font  types.  Users  running  the  label  file  option  thnxigh  d.display 
cannot  specify  these  options;  instead,  default  values  are  used  (see  d.label  for  default  values  used). 

Ihe  d.display  tool  is  best  learned  by  playing  with  its  options.  Refer  to  the  individual  d.  ;tnd  other 
commands  in  the  SliE  ALSO  section  for  a  detailed  examination  of  these  functions. 

NOTES 

Ihe  user  can  also  modify  the  current  region  settings  from  the  DISPI  AY  MAIN  MENU.  Using  the 
mouse,  tlx;  user  can  choose  to  zoom  in  on  a  p<xlion  of  the  displayed  raster  map  layer  to  create  a 
smaller  geographic  region.  Once  the  user  has  defined  the  comers  of  this  area  using  the  nnxi.se,  the 
smaller  area  is  enlarged  and  replotted  on  the  screen.  Ihe  user  can  similarly  choose  to  zoom  out.  In 
this  case,  the  user  uses  the  mcxise  to  encompass  tliat  portion  of  the  reduced  map  that  the  user  wishes  to 
make  the  current  geographic  region  arxl  display  in  the  center  of  me  screen.  Ihe  huger  map  is  then 
replotted  and  displayed.  Innallv,  the  user  can  enter  geographic  c<x>rdi nates  for  tlx1  region's  comers 
from  the  keyboard  using  the  GRASS  command  g. region.  This  is  done  by  selecting  the  type 
coordinates  option. 

Ihe  main  menu  also  offers  the  user  the  option  of  hiding  the  main  menu  for  ten  seconds  ( hide  menu  for 
10  seconds). 

Ihe  d.display  command  must  be  nui  in  conjiuiction  with  a  prog  nun  wltich  converts  the  GRASS 
graphics  commands  generated  by  d.display  to  the  graphics  commands  that  the  current  device 
understands.  This  device  will  almost  always  be  a  graphics  monitor.  On  most  systems  the  user  is 
required  to  start  up  this  other  program  separately  from  (and  prior  to)  d.display.  In  such  cases,  a 
locally-defined  program,  usually  "monitor',  is  used  (see  yixir  GRASS  manager).  (For  example,  on 
MASSCOMP  machines,  the  d.tnon  program  must  lx1  running  in  the  forcgrcxind  on  the  graphics  monitor. 
On  SUN  machines,  the  d.mon  [xogram  can  lx  started  from  any  tenninal  am!  nm  in  Ihe  backgnxind.) 

d.display  sends  program  cxitput  to  the  current  graphics  franx  (set,  by  default,  to  the  full  graphics 
screen  unless  modified  by  the  user).  You  can  use  d.frame  to  create  and  choise  a  smaller  display  frame 
on  the  graphics  monitor  for  use  by  d.display. 

See  the  GILASS  macro  3d.view*sh  stored  under  S GIS1  IASI  /sc ri pt s  for  an  example  of  how  y«xt  can 
create  a  d.display Wkc  macro  using  a  shell  script. 
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SEE  ALSO 

See  3d.viewsh  or  slide  show  sh  under  SGISBASE/scripts  for  examples  of  cLdisplay-like  macros. 

d.3d,  d. color  mode,  dxolors,  d.frame,  d.label,  d.legend,  d.measure,  tUnon,  d.rast,  dscale,  dsites, 
d.vect,  (Lzoom,  g.region,  p.menu,  and  v.digit 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.erase  -  finises  the  contents  of  the  active  display  frame  on  the  user’s  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.erase 
d.erase  help 
d.erase  [ color ^name] 

DESCRIPTION 

d.erase  erases  the  contents  of  the  active  graphics  frame,  and  replaces  it  with  the  color  black  (by 
default)  or  by  whatever  color  is  specified  by  the  user,  d.erase  will  not  alter  the  assignment  of  the 
active  frame. 

Parameter: 

color  =name  Color  with  which  active  frame  will  Ire  erased. 

Options:  red,  orange,  yellow,  green,  blue,  yellov  ,  indigo,  violet,  black,  white, 
gray,  brown,  and  magenta 
Default:  black 

SEE  ALSO 

d.frame,  d.mon 

AUTHOR 

James  Wcstervelt,  U.S.  Army  Constniction  Fog  i  nee  ring  Research  I  .alxiratory 
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NAME 

d.font  -  Selects  the  font  in  which  text  will  be  displayed  on  the  user’s  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

dioot 
d.font  help 
d.font  faat=namt 

DESCRIPTION 

d.font  allows  the  user  to  select  use  of  a  specific  text  font  for  display  of  text  on  the  graphics  monitor. 
The  GRASS  program  show.fonts.sh  is  a  UNIX  Bourne  shell  macro  which  names  and  displays  the  fonts 
that  can  be  selected  using  d.font.  If  the  user  does  not  specify  a  font  when  using  other  GRASS 
programs  that  display  text,  the  font  type  romans  is  used  by  default. 

The  user  can  run  this  program  either  non-interactively  or  interactively.  If  the  user  specifies  a  font  type 
name  on  the  command  line  the  program  will  run  non-interactively.  Alternately,  the  user  can  simply 
type  d.font  on  the  command  line;  in  this  case,  the  program  will  prompt  the  user  for  a  display  text  fou 
type  using  the  standard  GRASS  interface  described  in  the  manual  entry  for  parser. 

Parameter: 

font  =name  Name  of  a  font  type,  from  among  the  font  types  italicized  below. 

Default:  romans 
Options:  (italicized) 


cyrilc 

-  Cyrillic 

gothgbt 

-  Gothic  Groat  Britain  triplex 

golhgrt 

-  Gothic  German  triplex 

gothitt 

-  Gothic  Italian  triplex 

greeke 

-  Greek  complex 

greekes 

-  Greek  complex  script 

greekp 

-  Greek  plain 

greeks 

-  Greek  simple/. 

italiee 

-  Italian  complex 

italiccs 

-  T'  lian  complex  small 

italic t 

-  Italian  triplex 

romanc 

-  Goman  complex 

romancs 

-  Roman  comple:.  mail 

rorrand 

-  Roman  duplex 

~''munp 

-  Roman  plain 

'vans 

-  Roi  an  simplex 

>mant 

-  Roman  triplex 

riptc 

-  Script  complex 

scripts 

-  Script  simplex 

N<  ~ES 

Ihe  font  type  romans  is  the  fastest  font  ty jxj  to  display  to  the  graphics  monitor. 


SEE  ALSO 

dlt/IRO,  d.text,  d. title,  show.fonts.sh,  and  parser 


AUTHOR 

James  Wcstervelt,  U  S.  Army  Constmclion  lingineering  Research  Laboratory 

d.font  uses  the  public  domain  version  of  the  Ifcrshey  Fonts  created  by  Dr.  AV.  Hershev  while  working 
at  the  U  S.  National  Bureau  of  Standards. 
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NAME 

d.frame  -  Manages  display  frames  on  the  user’s  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

dJrame 
d .frame  help 

d.frame  [cepsD]  [frame  =name]  [at=bottom,top, left, right] 

DESCRIPTION 

This  program  manages  display  frames  on  the  user’s  graphics  monitor.  GRASS  display  programs  at 
rumtime  connect  with  graphics  rendering  programs.  While  the  display  programs  are  identic.il  on  every 
hardware  platform,  the  graphics  rendering  programs  are  (essentially  the  only  GRASS  programs) 
designed  for  individual  hardware  devices.  Ihese  rendering  programs  are  managed  with  the  GRASS 
program  d.mon.  Graphics  are  displayed  in  rectangular  frames  on  whatever  graphics  monitor  the  user  is 
currently  directing  GRASS  display  output  to.  These  frames  are  created  and  managed  with  this  program. 
Note  that  GRASS  frame  contents  are  not  retained  when  one  frame  covers  another.  You 
cannot  shuffle  frames  from  top  to  bottom  and  then  back  again.  They  simply  define  rectangular  areas  on 
the  screen  where  subsequent  drawing  will  occur,  d.frame. 

Flags: 

-c  Creates  a  new  display  frame  on  the  graphics  monitor. 

-e  Removes  all  existing  display  frames  and  reinitializes  the  entire  graphics  screen 

(the  full-screen  display  frame). 

-p  Prints  the  name  of  the  active  frame,  in  which  GRASS  display  output  will  appear. 

-s  Selects  a  frame  for  the  display  of  GRASS  graphics.  Ibis  frame  is  then  known  as 

the  "active  frame." 

-D  Prints  the  status  of  the  user’s  graphics  monitor  and  active  display  frame  to 

standard  output.  Information  includes  the  name  and  the  dimensions  of  the  current 
frame  on  the  graphics  monitor,  given  in  the  form  bottom  top  left  right.  This 
function  is  useful  for  debugging  output,  and  for  determining  display  screen 
coordi  nates. 

Parameters: 

frame  =name  The  name  of  the  display  frame  to  be  created/selected. 

at  =bottom,top,  left,  right 

Where  to  place  the  frame  (implies  -c).  Frame  coordinates  are  stated  in  the  form: 
bottom,top, left, right .  The  lower-left  comer  of  the  graphics  monitor  always  is  at 
location  0,0  while  the  monitor’s  upper-right  comer  is  always  at  100,100. 

NOTES 

If  the  user  has  created  multiple  display  frames  that  overlap  one  another,  whatever  the  user  displays  in 
the  active  frame  will  overwrite  those  portions  of  the  underlying  frame  where  these  frames  overlap. 

SEE  ALSO 

d.erase,  d.mon 

AUTHORS 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Michael  Shapiro,  U.S.  Army  G instruction  Engineering  Research  Laboratory 
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NAME 

d. geodesic  -  Displays  a  geodesic  line,  tracing  the  shortest  distance  between  two  geographic  points 
along  a  great  circle,  in  a  longitudeAatitude  data  set. 

(GRASS  Display  Program) 

SYNOPSIS 

dgeodesic 
dgeodesic  help 

d .geodesic  [coar  =lon  1, lot l,lon2,lat 2]  [lcolor=#U2/nr]  [tcolor  =name] 

DESCRIPTION 

d.geodesic  displays  a  geodesic  line  in  the  active  frame  on  the  user’s  graphics  monitor.  This  line  traces 
the  shortest  distance  between  two  user-specified  points  on  the  curved  surface  of  a  longitude/latitude  data 
set.  The  two  coordinate  locations  named  must  fall  within  the  boundaries  of  the  user’s  current 
geographic  region. 

COMMAND  LINE  OPTIONS 

This  program  can  be  run  either  interactively  or  noo-interactively.  If  the  user  types  d .geodesic  on  the 
command  line  without  other  program  parameters,  the  mouse  will  be  activated;  the  user  is  asked  to  use 
the  mouse  to  indicate  the  starting  and  ending  points  of  each  geodesic  line  to  be  drawn.  The  default  line 
color  (white)  and  text  color  (red)  will  be  used. 

Alternately,  the  user  can  specify  the  starting  and  ending  coordinates  of  the  geodesic,  line  color,  and  text 
color  on  the  command  line,  and  run  the  program  noo-interactively. 

Once  the  user  indicates  the  starting  and  aiding  coordinates  of  the  geodesic,  the  line  and  its  length  (in 
miles)  are  displayed  to  the  user’s  graphics  monitor. 

Parameters: 

coor  Jonl  ,lat  I ,Um2,lat2 

Starting  and  ending  coordinates,  in  longitude  and  latitude  values,  of  the  geodesic 
line  to  be  drawn. 

I  col  or  name  Line  color  in  which  geodesic  will  be  displayed. 

Options:  red,  orange,  yellow,  green,  Hue,  magenta,  indigo,  violet,  gray,  white. 
Hack 

Default:  white 

tcolor  =name  Text  color  in  which  the  length  of  the  geodesic  will  be  displayed. 

Options:  red,  orange,  yellow,  green,  Hue,  magenta,  indigo,  violet,  gray,  white. 
Hack. 

Default:  red 

NOTES 

This  program  works  only  on  GRASS  data  bases  using  a  longitude/latitude  coordinate  system. 

SEE  ALSO 

d.rhumbline 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.graph  -  Program  for  generating  and  displaying  simple  graphics  to  the  graphics  display  monitor. 
(GRASS  Display  Program) 

SYNOPSIS 

d.graph 
d.graph  help 

d.graph  [input  =name]  [calor=name] 

DESCRIPTION 

d.graph  draws  graphics  that  arc  described  either  from  standard  input  (default),  or  within  a  file  (if  an 
input  file  name  is  identified  on  the  command  line).  If  graphics  commands  are  entered  from  standard 
input,  a  ctrl-d  is  used  to  signal  the  end  of  input  to  d.graph. 

The  program  can  be  run  interactively  or  non- interactively.  The  user  can  run  die  program  completely 
non-interactively  by  specifying  the  name  of  a  graphics  file  containing  d.graph  graphics  commands  and 
the  values  of  all  needed  parameters  cm  the  command  line.  The  user  can  instead  elect  to  run  the 
program  jWtially  interactively,  by  specifying  any/all  of  the  parameters  except  the  graphics  file=rmme 
parameter  on  the  command  line.  In  this  case,  d.graph  will  expect  the  user  to  input  d.graph  graphics 
commands  from  standard  input  (i.e.,  the  keyboard)  and  will  (silently)  prompt  the  user  for  these  graphics 
commands. 

Alternately,  the  user  can  simply  type  d .graph  on  the  command  line,  and  be  prompted  for  the  values  of 
all  parameters  (the  user  can  still  input  graphics  commands  from  either  an  input  file  or  standard  input 
using  this  form).  In  this  case,  the  user  is  presented  with  the  standard  GRASS  parser  interface  described 
in  the  jnanual  entry  for  parser. 

Parameters: 

61  e=name  Name  of  file  containing  graphics  commands.  This  is  a  UNIX  file  name;  tire  file 

must  be  located  in  the  user’s  current  working  directory  or  be  specified  by  its  full 
path  name.  If  no  filename  is  specified  commands  are  taken  from  the  standard 
input. 

ccior=name  Starting  color  desired  for  graphics. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  Hack. 

Default:  white 

The  coordinate  system  used  is  0-100  in  x  and  0-100  in  y,  regardless  of  the  graphics  monitor  display 
frame  size  and  aspect.  The  (0,0)  location  is  the  lower  left  comer  of  the  active  graphics  monitor  display 
frame.  All  values  may  be  floating  point. 

The  graphics  language  is  simple,  and  uses  the  follcwing  commands: 

#  comment 

A  line  of  comment,  which  is  ignored  in  the  processing, 
move  Xpos  ypos 

The  current  location  is  updated  to  xpos  ypos.  Values  are  stated  as  a  percent  of  the  active 
display  frame’s  horizontal  (xpos)  and  vertical  (ypos )  size,  and  may  be  floating  point  values. 
Values  are  between  0-100.  Note.  A  space  must  separate  xpos  and  ypos. 

draw  xpos  ypos 

A  line  is  drawn  in  the  current  color  from  the  current  location  to  die  new  location  xpos  ypos, 
which  then  becomes  the  current  fixation.  Values  are  stated  as  a  percent  erf  the  active  display 
frame’s  horizontal  (xpos)  and  vertical  (ypos )  size,  and  may  be  floating  point  values.  Values 
are  between  0-100.  Note.  A  space  must  separate  xpos  and  ypos. 


GRASS  4.0  (Summer  I WI ) 


IJ.S.  Anns'  (  I  RI. 


30 


cLgraph 


GRASS  Reference  Manual 


d  .graph 


color  color 

Sets  the  current  color  to  that  stated;  subsequent  graphics  will  be  drawn  in  the  stated  color, 
until  the  current  color  is  set  to  a  different  color.  Options  are  red,  orange,  yellow,  green, 
blue,  indigo,  violet,  brown,  magenta,  gray,  white,  and  black. 

size  xper  yper 

Subsequent  text  will  be  drawn  such  that  the  text  is  xper  percent  of  the  graphics  monitor 
display  frame  wide  and  yper  percent  of  the  frame  high.  By  default,  the  text  size  is  set  to  1 
percent  of  the  active  frame’s  width  and  1  percent  of  the  frame’s  height  if  unspecified  by  the 
user  (this  may  be  too  small  to  be  seen  by  the  user). 

Note.  A  space  must  separate  xper  and  yper. 

text  line-of-text 

The  stated  text  is  drawn  at  the  current  location  using  the  current  color,  and  die  new  current 
location  is  then  positioned  at  the  end  of  the  text  string. 

icon  type  size  x  y 

Draws  an  icon  of  types  o,  x,  or  +  with  specified  size  at  location  x,y.  Note:  type  o  designates 
a  square. 

polygon 

xposypos 

xposypos 


The  coordinates  appearing  beneath  the  word  polygon,  one  pair  per  line,  circumscribe  a 
polygon  that  is  to  be  filled  with  the  current  color. 

EXAMPLE 

For  an  example  use  of  d.graph,  examine  the  contents  erf  the  macro  command 
$GISBASE/bin/grass.logojh,  located  in  the  GRASS  command  bin  (winch  draws  a  GRASS  logo  by 
inputting  d.graph  graphics  commands  that  are  stored  in  a  shell  file).  Note  that  the  coordinates  in  the 
grass. logosh  macro  were  taken  directly  off  an  image  drawn  by  hand  on  graph  paper. 

NOTES 

d.graph  remembers  the  last  screen  location  (xpos  ypos)  to  which  the  user  moved,  even  after  the  user 
erases  the  display  frame.  If  the  user  runs  (Lgraph  repeatedly,  and  wishes  to  start  anew  with  the  default 
(xpos  ypos)  screen  location,  the  user  should  clear  the  display  frame  between  runs  of  cLgraph. 

LIMITATIONS 

There  are  no  automated  ways  of  generating  graphic  images.  It  is  anticipated  that  GRASS  user  sites  will 
write  programs  to  convert  output  from  a  resident  graphics  editor  into  GRASS  cLgraph  format. 

SEE  ALSO 

d-INTRO,  d.font,  d.mapgraph,  d.text,  grass.logojh,  and  parser 
AUTHOR 

James  Westervelt,  U.S.  Army  Constniction  Engineering  Research  Laboratory 
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NAME 

d.grid  -  CVerlays  a  user- specified  grid  in  the  active  display  frame  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d-grid 
d.grid  help 

d.grid  si ut=value  [color  =name]  [origin  =easting,northing] 

DESCRIPTION 

d.grid  overlays  a  grid  of  user-defined  size  and  color  in  the  active  display  frame  on  the  graphics 
monitor.  The  grid  will  overlay,  not  overwrite,  the  contents  of  the  active  display  frame. 

d.grid  can  U  run  non  interactively  or  interactively.  If  the  user  specifies  the  grid  size  and  (optronally ) 
the  grid  color  on  the  command  line  the  program  will  run  non  interactively;  if  no  grid  color  is  given 
the  default  will  be  used.  Alternately,  the  user  may  simply  type  d.grid  on  the  command  line;  in  this 
case,  the  program  will  prompt  the  user  for  parameter  values  using  the  standard  GRASS  user  interface 
described  in  the  manual  entry  for  parser. 

Parameters : 

si z e=value  Size  of  grid  to  be  drawn  in  the  active  display  frame,  in  current  map  coordinate 

system  units.  It  should  be  noted  that,  depending  on  the  scale  of  the  map  layer 
displayed  in  this  frame,  the  grid  may  fall  outside  the  user’s  viewing  range. 

Options:  0-100000 

color  =name  Sets  the  current  grid  color  to  name. 

origin  =easting,northing 

Lines  of  the  grid  pass  through  this  coordinate.  The  coordinate  need  not  be  within 
the  current  frame. 

Options:  red,  orange,  yellow,  green.  Hue,  indigo,  violet,  magenta,  brown,  gray  , 
white,  and  Hack. 

Default:  gray 

NOTES 

d.grid  will  not  erase  grids  already  displayed  in  the  active  graphics  display  frame  by  previous 
invocations  of  d.grid;  multiple  invocations  of  d.grid  will  therefore  result  in  the  drawii^  of  multiple 
grids  inside  the  active  graphics  frame.  (A  command  like  d.erase,  winch  erases  the  entire  contents  of 
the  active  display  frame,  must  be  run  to  erase  previously  drawn  grids  from  the  display  frame.) 

Currently,  the  grid  size  can  only  be  drawn  in  the  units  of  the  map  coordinate  system  used  by  the  current 
GRASS  1  (cation. 

SEE  ALSO 

d.display,  eLerase,  d.frame,  d.  legend,  d.rast,  djeale,  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

dJiis  -  Produces  and  displays  a  raster  map  layer  combining  hue,  intensity,  and  saturation  (his)  values 
from  user-specified  input  raster  map  layers. 

(GRASS  Display  Program) 

SYNOPSIS 

dJiis 

dills  help 

dJiis  hjnap=mvw  [Lmap^um]  [s  mapna/r*’]  [aat=name\ 

DESCRIPTION 

his  stands  for  hue,  intensity,  and  saturation.  This  program  produces  a  raster  map  layer  providing  a 
visually  pleasing  combination  of  hue,  intensity,  and  saturation  values  from  two  or  three  user-specified 
raster  map  layers. 

The  human  brain  automatically  interprets  the  vast  amount  of  visual  information  available  according  to 
basic  rules.  Color,  or  hue,  is  used  to  categorize  objects.  Shading,  or  intensity,  is  interpreted  as  three- 
cfimensional  texturing.  Finally,  the  degree  of  haziness,  or  saturation,  is  associated  with  distance  or 
depth.  This  program  allows  data  from  up  to  three  raster  map  layers  to  be  combined  into  one  new  raster 
map  layer  that  retains  the  original  information  in  terms  of  hue,  intensity,  and  saturation. 

OPTIONS 

This  program  can  be  run  non-interactively  or  interactively.  It  will  run  non- interactively  if  the  user 
specifies  on  the  command  line  the  name  of  a  map  containing  hue  values  (h _map),  and  the  name(s)  of 
map(s)  containing  intensity  values  ( ijnap )  and/or  saturation  values  ( s_jnap ).  If  the  user  also  names  an 
output  map  (out)  on  the  command  line,  the  combined  hue,  saturation,  and  intensity  values  will  be  saved 
as  a  raster  map  layer  in  the  user’s  current  mapset;  otherwise,  the  resulting  image  will  only  be  displayed 
in  the  active  display  frame  on  the  graphics  monitor. 

Alternately,  the  user  can  run  the  program  interactively  by  typing  dJiis  without  naming  parameter 
values  on  the  command  line.  In  fins  case,  the  program  will  prompt  the  user  far  parameter  values  using 
file  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 


Parameters: 

map  =nu/ne 
Lmap  =name 
a_map  =name 
ouiname 


Name  of  input  raster  map  layer  to  be  used  for  HUE  values. 

Name  of  input  raster  map  layer  to  be  used  for  INTENSITY  values. 

Name  of  input  raster  map  layer  to  be  used  for  SATURATION  values. 

Name  of  the  output  raster  map  layer  combining  hue,  intensity,  and  saturation 
values  from  input  layers. 


While  any  raster  map  layer  can  be  used  to  represent  the  hue  information,  map  layers  with  a  few  very 
distinct  colors  work  best.  Only  raster  map  layers  representing  continuously  varying  data  like  elevation, 
aspect,  weights,  intensities,  or  amounts  can  suitably  be  used  to  provide  intensity  and  saturation 
information. 

For  example,  a  visually  pleasing  raster  map  layer  can  be  made  by  using  a  watershed  map  for  the  hue 
factor,  an  aspect  map  for  the  intensity  factor,  and  an  elevation  map  for  saturation.  (The  user  may  wish 
to  leave  out  the  elevation  information  for  a  first  try.)  Ideally,  the  resulting  image  should  resemble  the 
view  from  an  aircraft  looking  at  a  terrain  on  a  sunny  day  with  a  bit  of  haze  in  the  valleys. 

THE  PROCESS 

Each  map  cell  is  processed  individually.  First,  the  working  color  is  set  to  the  color  of  the 
corresponding  cell  in  the  map  layer  chosen  to  represent  HUE.  Second,  this  color  is  multiplied  by  the 
red  intensity  of  that  cell  in  the  INTENSITY  map  layer.  This  map  layer  should  have  an  appropriate 
gray- scale  color  table  associated  with  it.  You  can  ensure  this  by  using  the  color  manipulation 
capabilities  of  d.display  <r  d.ccAors.  Finally,  the  color  is  made  somewhat  gray-based  on  the  red 
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intensity  of  that  cell  in  the  SATURATION  map  layer.  Again,  this  map  layer  should  have  a  gray  scale 
color  table  associated  with  it. 

NOTES 

This  program  produces  an  image  and  (optionally)  a  raster  map  layer  with  1000  colors  (10  intensities 
each  of  red,  green,  and  blue).  The  resulting  image  and  raster  map  layers  will  not  display  properly  if  the 
graphics  display  monitor  does  not  have  at  least  1000  colors  while  the  user  is  running  in  float 
colormode.  Thus,  unless  the  display  device  has  1000  colors,  it  is  necessary  to  run  the  GRASS 
command 

d .colormode  mode  =fixt  < 

before  running  d.his.  Otherwise,  the  colors  will  be  incorrectly  displayed  on  the  graphics  monitor. 

Ether  (but  not  both)  of  the  intensity  or  the  saturation  map  layers  may  be  omitted.  I  his  means  that  it  is 
possible  to  produce  output  images  that  represent  combinations  of  his,  hi,  or  hs. 

SEE  ALSO 

d.3d,  d.coiormode,  d.coiors,  d.coiortable,  (Ldisplay  hsvjgb^h,  rgbJisvjh  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i ihistogram  -  Displays  a  histogram  in  the  form  of  a  pie  or  bar  chart  for  a  user-specified  raster  file. 
(GRASS  Display  Program) 

SYNOPSIS 

dJustogrmm 
d .histogram  help 

d .histogram  [-zq]  mmp=name  [color  =/uwne]  [ style  =nome] 

DESCRIPTION 

d.histogram  displays  the  category-value  distribution  for  a  user-specified  raster  map  layer,  in  the  form  of 
a  bar  chart  or  a  pie  chart.  The  display  will  be  displayed  in  the  active  display  frame  on  the  graphics 
monitor,  using  the  colors  in  the  raster  map  layer’s  color  table.  The  program  determines  die  raster  file’s 
category  value  distribution  by  counting  cells. 

OPTIONS 

The  user  can  run  this  program  either  non- interactively  or  interactively.  The  program  will  be  run  non¬ 
in  teractiv  el  y  if  the  user  specifies  the  name  of  a  raster  map  layer  and  (optionally)  any  other  desired 
parameters  and  flags  on  the  command  line,  using  the  form: 

d .histogram  [-zq]  map=name  [color  =namc]  [ style  =name] 

If  a  map  name  is  given  on  the  command  line,  any  other  parameter  values  left  unspecified  on  the 
command  line  will  be  set  to  their  default  values  (see  below).  Alternately,  the  user  can  simply  type 
d .histogram  on  the  command  line,  without  program  arguments.  In  this  case,  the  user  will  be 
prompted  for  needed  inputs  and  option  choices  using  the  standard  GRASS  user  interface  described  in 
the  manual  entry  for  parser. 

Flags: 

-z  Display  zero-data  information  (cells  with  category  value  zero)  in  the  histogram. 

If  the  -z  flag  is  set,  then  cells  with  category  value  0  in  the  named  raster  map  layer 
will  be  included  in  the  pie  or  bar  chart.  If  this  Bag  is  not  set,  then  cells  with 
category  value  0  will  be  excluded  from  the  bar  chart. 

-q  Gather  the  histogram  quietly,  without  printing  messages  on  program  progress  to 

the  user’s  terminal. 

Parameters: 

map  =name  The  name  of  an  existing  raster  map  layer  in  the  user’s  current  mapset  search  path 

for  which  a  histogram  is  to  be  displayed. 

color  =aame  The  name  of  the  color  to  be  used  for  the  axis,  text-labels,  and  tic-marks  on  the 

pie  or  bar  chart. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  magenta,  violet,  brewn, 
gray,  and  black. 

Default:  color  =white 

ftjle=name  The  style  of  the  histogram.  If  atyle=bar,  then  dJustogram  will  display  the 

statistics  in  the  form  of  a  bar  chart.  If  atylc=pic,  then  d.Hstogram  will  display 
the  statistics  in  the  fonn  erf  a  pie  chart. 

Options:  bar  tr  pie 
Default:  style  =bar 

NOTES 

d.histogram  uses  the  current  geographic  region  settings  and  the  current  mask  (if  one  exists). 

d.histogram  uses  the  colors  in  the  map’s  color  look-up  table  (i.c.,  the  map’s  coir  or  coir2  file).  To 
view  results  correctly  on  the  display  monitor,  make  sure  the  color  mode  is  correctly  set  before  running 
d.histogram  (i.e.,  set  d.colorinode=flaat). 
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d.histogram  does  not  erase  the  active  frame  before  displaying  output. 

SEE  ALSO 

d.colormode,  d.colors,  dxolortable,  d.display,  d.erase,  g.region,  r.mask,  rjtats,  and  parser 

AUTHOR 

Dbvid  Johnson 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

dicons  -  Displays  points,  as  icons,  at  user-defined  locations  in  the  active  display  frame  on  the  graphics 
monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d  .icons 
d  Jeans  help 

d Jeans  [-r]  icon  -name  [color  =name]  [dze=value]  [points=name] 

DESCRIPTION 

dicons  graphically  displays  point  (site)  locations  as  icons  in  the  active  frame  on  die  graphics  monitor. 
Geographic  coordinates  are  read  either  from  standard  input  or  from  an  input  file  whose  name  is  stated 
by  the  user.  At  each  site  location,  a  user-defined  icon  is  displayed 

OPTIONS 

The  user  must  enter  at  least  the  name  of  an  icon  file  storing  a  graphic  representation  of  the  icon  to  be 
displayed,  and  the  geographic  coordinates  of  the  points  at  which  they  will  appear. 

The  user  can  run  this  program  either  non- interactively  or  interactively.  The  program  will  be  run  non- 
interactively  if  the  user  specifies  the  name  of  an  icon  file  and  (optionally)  any  other  desired  parameters 
on  the  command  line,  using  the  form: 

d.icons  [-r]  icon  =name  [color  ==na#ne]  [size  =value\  [points=ruz/nej 

If  the  user  fails  to  specify  the  name  of  a  points  file  on  the  command  line,  the  program  will  prompt  the 
user  to  enter  geographic  coordinates  from  standard  input.  If  the  user  specifies  at  least  the  name  cf  an 
icon  file  on  the  command  line,  any  other  parameter  values  left  unspecified  by  the  user  will  be  set  to 
their  default  values  (see  belcw). 

Alternately,  the  user  can  simply  type: 
d.icons 

on  the  command  line,  without  program  arguments.  In  this  case,  the  user  will  be  prompted  for  needed 
parameter  values  using  the  standard  GRASS  user  interface  described  in  the  manual  entry  for  parser. 
The  geographic  coordinates  at  which  icons  are  to  be  displayed  can  still  be  input  from  an  input  file 
( points )  in  interactive  use. 


Flag: 

-r 

Coordinates  are  input  in  reverse  order  (i.e.,  as  northing  easting). 

Parameters: 

icon  name 

The  name  of  an  existing  file  containing  a  graphic  representation  of  the  icon  to  be 
drawn,  icon  files  can  be  created  by  the  user  using  the  p.icons  command  and  are 
stored  under  the  icons  directory  under  the  user’s  current  mapset. 

color  name 

Sets  the  current  icon  color  to  the  name  stated. 

Options:  red,  orange,  yellow,  green,  Hue,  iixligo,  violet,  gray,  white,  and  black 
Default:  color  white 

size  =value 

The  icon  scaling  factor. 

Options:  1-1000 

Default:  size=l 

points  =name 

The  name  of  a  UNIX  file  containing  the  geographic  coordinates  of  sites  at  which 
icons  are  to  be  drawn.  Since  this  is  a  UNIX  file,  the  user  slmuld  specify  the  name 
using  standard  UNIX  file  i tuning  conventions.  If  this  file  is  not  in  the  user’s 
current  working  directory,  its  pathname  sfiould  be  specified.  The  rile  contents 
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should  consist  of  a  series  of  geographic  coordinates  that  fall  within  the  boundaries 
of  the  current  geographic  region.  Each  site  location  should  be  stated  on  a 
separate  line  as  an  easting  and  northing  (in  that  order)  separated  by  a  sir^le  Wank 
space.  If  no  points  file  is  specified  by  the  user,  input  is  taken  from  standard  input 
and  should  be  given  in  the  same  form;  to  end  standard  input,  type  end  (or  press 
control -d). 

EXAMPLE 

An  icons  file  contains  a  graphic  representation  of  the  icon  to  be  displayed.  Here,  spaces  represent  areas 
of  no  color,  and  x’s  represent  areas  of  color.  For  example,  the  user  might  construct  an  icon  resemWing 
a  cross  in  the  following  way: 

x 

x 

xxxxx 

X 

X 

X 

This  icon  might  be  stored  in  a  file  called  cross  (under  the  user’s  SLOCATION/icons  directory).  If  the 
user  specified  that  this  be  the  icon  file  used  while  running  d.icons,  this  cross  would  then  appear  in  the 
color  and  size  specified  by  the  user,  at  each  site  location  named  in  the  points  file. 

Note:  icons  are  created  with  the  p.icons  command. 

Ilie  points  file  lists  the  geographic  coordinates  of  site  locations  (at  which  icons  will  be  displayed). 
This  file  shtxild  take  the  form: 

easting  nothing 
easting  northing 
easting  northing 

If  the  user  sets  the  r  flag,  the  order  of  these  coordinates  should  be  reversed  (i.e.,  coordinates  should  be 
given  as  northing  easting ). 

If  the  points  file  is  not  specified,  then  the  corrclinates  are  read  from  the  keyboard  or  across  a  pipe.  Iliis 
feature  allows  users  to  enter  the  coordinates  by  hand,  or,  more  usefully,  to  get  then  from  another 
program.  For  example,  to  display  icons  at  locations  specified  in  a  sites  list: 
s.out.ascii  name  j  d-icons  icon=cross 

where  name  is  the  name  of  a  site  list,  and  cross  is  the  nome  of  an  icon. 

SEE  ALSO 

d. points,  d.sites,  d.where,  p.icons,  s.dh,  s.oul. ascii,  v.dh,  and  parser 

AUTHORS 

Contributed  by: 

David  Johnson 
DBA  Systems.  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 

Modified  by: 

Michael  Shapiro 

U  S.  Army  Construction  Engineering  Research  lalxiratorv 
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NAME 

dJabel  -  Creates  and  displays  text  labels  in  the  active  display  frame  an  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

dJabd 
dJabel  help 

dJabel  [riz e=value]  [backcolor  =/uvne]  [texted or  =name]  [font  =name] 

DESCRIPTION 

dJabel  allows  the  user  to  create  and  display  text  labels  in  the  active  frame  on  the  graphics  monitor.  It 
interactively  requests  that  the  user  type  in  text  and  use  the  pointing  device  (mouse)  to  identify  where 
this  text  is  to  be  placed  within  the  active  graphics  frame.  7he  program  will  prompt  the  user  for  label 
size,  background  color,  text  color,  and  text  font  type,  if  the  user  fails  to  specify  these  values  on  the 
command  line.  Program  prompts  use  die  standard  GRASS  parser  interface  described  in  the  manual 
entry  for  parser. 

Parameters: 

size  --value  Sets  the  label  text  size  to  the  specified  number.  Values  are  stated  as  a  percentage 

of  the  frame  height;  e.g.,  a  size  of  10  will  make  each  line  of  text  equal  to  one- 
tenth  the  height  of  the  display  frame. 

Options:  0-1000 
Default:  10 

backcolor  name  Sets  the  color  of  the  label  background  to  the  name  stated. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  white,  and  Mack. 
Default:  black 

textcolor  =name  Sets  the  color  of  the  label  text  to  the  name  stated. 

Options:  same  as  for  backcolor. 

Default:  white 

tant=name  Sets  the  font  type  used  for  the  label’s  text  to  name. 

Options:  romand,  romanp,  romant,  romans,  scriptc,  scripts,  romancs,  italiee, 
italiccs,  gothitt,  gothgrt,  and  gothgbt.  The  user  can  view  these  available  fonts  by 
running  show  fonts  jh. 

Default:  romans  (Roman  simplex  font  type),  or  whatever  font  the  user  has  set 
the  font  type  to  before  entering  dJabel. 

NOTES 

This  program  will  allow  the  user  to  display  labels  anywhere  in  the  active  display  frame,  even  in  areas 
lying  outside  of  the  current  geographic  region. 

d.label  will  only  allow  the  user  to  type  in  one  line  of  text.  The  fully  interactive  program  dJabels  can 
be  used  to  create  text  labels  having  as  many  as  four  lines. 

dJabel  does  not  create  paint  labels  files  displayable  by  d.paint.labcls  -  dJabels  does.  These 
programs  should  be  integrated  in  future  GRASS  releases. 

BUGS 

If  the  user  is  running  GRASS  under  X  Windows,  and  the  user  enters  a  text  label  longer  than  80 
characters  (i.e.,  allows  text  to  wrap  onto  a  second  line),  X  Windows  will  stop  the  user’s  GRASS 
graphics  monitor  without  throwing  the  user  out  of  GRASS.  If  this  happens,  the  user  should  simply 
restart  a  graphics  monitor,  using  djnon. 
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SEE  ALSO 

d.(tisplay,  d.font,  d.labels,  d.legend,  d.mon,  cLpaint. labels,  d.rast,  descale,  d.text,  uJitle,  d.where, 
show.fontsjh  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

d.labels  -  To  create/edit  GRASS  paint  label  files  for  display  on  the  graphics  monitor. 

( GRASS  Display  Program) 

SYNOPSIS 

dJabels 

DESCRIPTION 

The  d.labels  program  allows  the  user  to  interactively  create  and  modify  paint-labels  files  for  use  with 
the  pjnap  and  (Lpaint. labels  programs.  The  paint  labels  files  created  will  be  stored  in  the  user's 
current  mapset  under  the  /paint /labels  directory. 

d.labels  is  fully  interactive,  and  requires  use  of  a  graphics  monitor.  After  the  user  has  typed 

dJabds 

and  has  typed  in  the  name  of  a  new  or  existing  paint-labels  file,  the  user  is  asked  to  indicate  label 
positions  on  the  display  frame  using  the  mouse-pointer,  and  to  edit  label  parameters  that  define  the 
label’s  size,  color,  and  other  characteristics  through  use  of  a  visual-ask  (VASK)  data  entry  screen.  The 
mouse  can  also  be  used  to  indicate  the  geographic  coordinates  of  locations  within  the  current 
geographic  region  in  the  active  frame.  It  is  helpful  to  display  a  relevant  data  file  in  the  active  display 
frame  before  running  d.labels  to  provide  visual  clues  for  label  placement. 

USER  PROMPTS 

You  will  first  be  prompted  to  enter  the  name  of  either  an  old  paint-labels  file  that  you  wish  to  modify, 
or  a  new  paint-labels  file  that  you  wish  to  create.  The  following  is  fire  file  name  prompt: 

Enter  the  name  of  an  existing  labels  file 
Enter  list  for  a  list  of  existing  labels  files 
Hit  RETURN  to  cancel  request 

> 

If  you  enter  the  name  of  a  new  (non-existent)  paint-labels  file,  you  are  asked  to  indicate  a  location 
falling  within  the  current  geographic  region  in  the  active  <5 splay  frame  at  winch  the  label  is  to  be 
placed. 


Mouse  Buttons 
Left:  Place  Label  Here 
Middle:  Where  Am  I  ? 

Right:  Quit 

Oice  you  have  indicated  a  position,  you  will  be  presented  with  a  data- entry  screen  (also  known  as  a 
VASK  screen)  so  that  you  can  enter  die  paint-label  parameters  that  define  how  the  label  will  appear  on 
the  display  or  on  the  color  printer.  Once  you  finish  entering  the  label-parameters,  and  you  hit  the 
<ESC>  key  to  proceed,  the  label  will  be  displayed  on  the  screen.  If  you  like  the  appearance  of  the 
label,  enter  "y”  to  the  "Lode  OK?'  prompt;  if  not,  enter  ”n"  and  you  will  again  be  presented  with  the 
data  entry  screen.  Once  you  approve  the  label’s  appearance,  you  will  be  asked  to  indicate  the  position 
of  the  next  label. 

If  you  choose  to  display  an  already-existing  paint-labels  file,  you  will  be  shown  the  labels  in  that  file 
one  at  a  time.  For  each  label,  you  will  be  asked:  "Look  OK?'  If  you  answer  "n”  to  the  "Look  CSC?' 
prompt,  you  will  be  presented  with  the  data  entry  screen  so  that  you  may  modify  the  appearance  of  the 
label  to  your  liking. 

Qvline  help  is  available.  If  you  are  puzzled  about  what  should  go  in  a  data  entry  field,  just  enter 
"help"  in  that  field,  hit  the  <ESC>key,  and  you  will  be  presented  with  a  short  description  of  the  field 
and  what  you  may  enter 
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I  he  following  is  a  list  of  the  different  fields  in  the  data  entry  screen  and  a  si  tori  description  of  each. 
TEXT:  The  user  can  enter  up  to  four  lines  of  text. 

SKIP:  yes/no.  If  no,  label  will  be  printed.  If  yes,  the  label  will  be  retained  in  the  file  but 
not  printed. 

LOCATION:  Determines  where  the  text  will  be  located.  The  user  specifies  the  easting 
and  northing  in  map  units,  and  (optionally)  specifies  a  vertical  and  horizontal  offset  (in 
printer  pixels)  from  the  specified  easting/northing.  (The  vertical  (y)  offset  will  shift  the 
location  to  the  south  if  positive,  north  if  negative.  The  horizontal  (x)  offset  will  shift  the 
location  east  if  positive,  west  if  negative.)  These  offsets  are  provided  to  allow'  finer 
placement  of  labels. 

RESET  LOCATION:  yesAio.  If  yes,  the  user  will  be  allowed  to  use  the  mouse  to  select 
a  new  location  for  the  label.  The  mouse  buttons  will  function  as  follows: 

Mouse  Buttons 
Left:  Place  Label  Here 
Middle:  Where  Am  I  ? 

Right:  Quit 

PLACEMENT:  Determines  which  part  of  the  label  to  which  the  location  refers.  This  may 
be  specified  as: 

lower  left  (lower  left  comer  of  the  text) 

lower  right  (lower  right  comer  of  the  text) 
lower  center  (bottom  center  of  the  text) 

upper  left  (upper  left  comer  of  the  text) 

upjper  right  (upper  right  comer  of  the  text) 
upper  center  (top  center  of  the  text) 

center  (center  of  the  text) 

TEXT  SIZE:  Determines  the  size  of  the  lettering  used  in  the  label.  Text  size  (height)  is 
stated  in  units  of  (ground)  meters;  eg.,  a  text  size  erf  500  sets  the  height  of  each  line  of  text 
equal  to  500  ground  meters.  Thus,  text  will  appear  to  grow  or  shrink  when  displayed, 
depending  on  the  useri  s  current  geographic  region  settings. 

TEXT  COLOR:  This  selects  the  text  color.  This  color  can  be  specified  in  one  of  three 
ways: 

1)  By  color  name: 

aqua  Hack  Hue  brown  cyan  gray  green  grey  indigo  magenta  orange  pxuprfe  red 
violet  white  yellow 

2)  As  red,  green,  Hue  percentages.  For  example:  5  .4  .7 

(This  form  is  not  supported  by  cLpaint labels,  but  see  pjnap  and  p. labels.) 

3)  By  painter  color  number,  to  get  the  exact  printer  color. 

(This  form  is  not  supported  by  d.  paint. lobe  Is,  but  see  pjnap  and  p.labels.) 
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Note.  If  the  user  sets  the  text  color  equal  to  the  background  color,  the  text  will  not 
appear  on  the  graphics  monitor. 

WIDTH:  This  determines  the  line  thickness  of  the  letters.  The  normal  text  width 
should  be  set  to  1.  Larger  numbers  can  be  used  to  simulate  bold  face. 
(d.paint. labels  ignores  this  value  and  always  uses  1.) 

HIGHLIGHT  COLOR:  The  text  can  be  highlighted  in  another  color  so  that  it 
appears  to  be  in  two  colas.  The  text  is  drawn  first  in  this  color  at  a  wider  line 
width,  and  then  redrawn  in  the  text  cola  at  the  regular  line  width.  Highlight  colors 
are  not  shown  on  the  graphics  display,  they  are  only  shown  in  the  output  from 
p.  labels  and  p.map 

HIGHLIGHT  WIDTH:  Specifies  how  far  from  the  text  lines  (in  pixels)  the 
highlight  cola  should  extend.  Hghlight  colors  are  not  shown  on  the  graphics 
display,  they  are  only  shown  in  the  output  from  p labels  and  pjrtap. 

BACKGROUND  COLOR:  Text  may  be  boxed  in  a  solid  cola  by  specifying  a 
background  color  (see  TEXT  COLOR,  above  to  specify  a  color).  Specify  none  to 
use  no  background. 

OPAQUE  TO  VECTORS:  yes/no.  This  field  only  has  meaning  if  a  background 
cola  is  selected,  yes  will  prevent  vector  lines  from  entering  the  background,  no 
will  allow  vector  lines  to  enter  the  background. 

BORDER  COLOR:  Select  a  cola  for  the  border  around  the  background.  Specify 
none  to  suppress  the  border. 


NOTES 

This  program  is  fully  interactive  and  requires  no  command  line  arguments. 

If  file  user  types  the  wad  help  in  a  data  entry  field  while  entering  label  information,  acceptable  field 
choices  will  be  listed. 

Labels  must  be  placed  within  the  current  geographic  region.  If  the  user  attempts  to  place  a  label 
outside  of  this  region,  the  program  will  appear  to  loop  endlessly.  It  is  amply  failing  to  display  a  label 
positioned  bey  aid  the  boundaries  of  the  current  region;  in  this  event,  the  user  should  simply  reposition 
the  label. 

Labels  created  by  this  program  are  stored  in  ASCII  files  under  the  directory  SLCXIATION^Mint^abels. 
SEE  ALSO 

d.label,  d.paint. labels,  d.rast,  rLvect,  d.where,  p labels,  pjnap 

AUTHOR 

Dhvid  Johnson 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

d.legend  -  Displays  a  legend  for  a  raster  map  layer  in  the  active  frame  on  the  graphics  monitor. 
(GRASS  Display  Program) 

SYNOPSIS 

dJegcnd 
dJegend  help 

dJegend  map  na,ne  [color  =name]  [lines=vo/ue) 

DESCRIPTION 

d.legend  displays  a  legend  for  a  user-specified  raster  map  layer  in  the  active  frame  cm  the  graphics 
monitor.  The  legend’ s  size  is  based  on  the  height  of  the  active  frame.  The  user  should  therefore  take 
care  to  create  a  display  frame  of  suitable  dimensions  before  running  dJegend.  d.legend  will  only 
obscure  those  portions  of  the  active  frame  that  directly  underlie  the  legend. 

The  user  can  run  dJegend  either  non-interactively  or  interactively.  If  the  user  specifies  the  name  of  a 
raster  map  layer  on  the  command  line,  the  program  will  nin  non-interactively.  Default  legend  text 
color  and  number  erf  lines  will  be  used  unless  the  user  specifies  other  values  on  the  command  line. 

Alternately,  the  user  can  simply  type  dJegend  on  the  command  line;  in  this  case,  the  program  will 
prompt  the  user  for  parameter  values  using  the  standard  GRASS  parser  interface  described  in  the 
manual  entry  for  parser. 

Parameters: 

map  -name  Name  of  a  raster  map  layer  whose  legend  is  to  be  displayed  in  the  active  display 

frame. 

color  =name  Sets  the  legend  text  color  to  the  name  stated. 

Options:  red,  orange,  yellow',  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  black. 

Default:  white 

lines  =value  Number  of  lines  to  appear  in  the  map  legend. 

The  number  of  lines  refers  to  the  maximum  number  of  lines  of  type  that  can  lx 
displayed  given  the  height  of  the  active  display  frame.  If  unspecified  by  the  user, 
the  program  will  divide  the  display  frame  into  the  number  of  lines  required  to 
display  all  of  the  category  labels  and  colors  associated  with  the  named  map.  To 
decrease  the  size  of  the  displayed  text,  increase  the  number  of  hires. 

Options:  1  -  1000 

Default:  Set  lines  value  equal  to  the  number  of  map  categories 

NOTES 

The  legend  text  size  is  based  on  the  number  of  lines  requested  (or,  by  default,  on  the  number  of  lines 
needed  to  display  tlx  legend).  If  the  user  attempts  to  display  a  very  long  legend  in  a  relatively  slum 
display  frame,  the  legend  may  appear  in  unreadably  small  text. 

SEE  ALSO 

dxolormode,  d.colors,  d.colortable,  d.display,  d.erase,  d.font,  d.frame,  d.grid,  d.label,  d.labels, 
d.rast,  d.scale,  and  parser 

AUTHOR 

James  Westervc! t,  U  S.  Army  Coirstniction  I  jigiucering  Research  Laboratory 
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NAME 

d.mapgraph  -  Generates  and  displays  simple  graphics  on  map  layers  drawn  in  the  active  graphics 
monitor  display  frame. 

(GRASS  Display  Program) 

SYNOPSIS 

djnapgraph 
djnapgraph  help 

d.mapgraph  [input  =ruz/ne]  [ color  =name]  [vsiz *=value]  [ha ite=value] 

DESCRIPTION 

d.mapgraph  draws  graphics  that  are  described  in  standard  input  (default)  or  the  UNIX  input  file  name. 
If  commands  are  entered  via  standard  input,  a  ctrl-d  is  used  to  signal  the  end  of  input  to  djnapgraph. 

I  his  program  performs  essentially  the  same  function  as  d.graph,  hew  ever,  point  locations  are  specified 
to  djnapgraph  in  the  geographic  coordinate  system  of  the  user's  current  mapset  and  location  (i.e.,  in 
map  coordinates),  rather  than  in  graphics  display  screen  coordinates. 

The  program  can  be  run  interactively  or  non-interactively.  The  user  can  run  the  program  completely 
non- interactively  by  specifying  the  name  of  a  file  containing  djnapgraph  graphics  commands  and  the 
values  of  all  needed  parameters  on  the  command  line.  The  user  can  instead  elect  to  run  the  program 
partially  interactively,  by  specifying  any /all  of  the  parameters  except  the  graphics  input  =name 
parameter  on  the  command  line.  In  this  case,  djnapgraph  will  expect  the  user  to  input  djnapgraph 
graphics  commands  from  standard  input  (i.e.,  the  keyboard)  and  will  (silently) -prompt  the  user  for  these 
graphics  commands.  Alternately,  the  user  can  simply  type  djnapgraph  on  the  command  line,  and  be 
prompted  for  the  values  of  all  parameters  (the  user  can  still  input  graphics  commands  from  an  input  file 
using  this  form.)  In  this  case,  the  user  is  presented  with  the  standard  GRASS  parser  interface  described 
in  the  manual  entry  for  parser. 

Parameters: 

input  name  Name  of  a  UNIX  file  containing  graphics  instructions.  Specify  the  full  path  name 

of  the  file  if  not  in  the  current  directory.  If  no  file  name  is  given,  commands  are 
taken  from  standard  input. 

color  name  Starting  color  desired  for  graphics. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  Mack. 

Default:  white 

d.mapgraph  is  used  for  drawing  simple  graphics  chi  top  of  map  layers.  The  coordinate  system  used  by 
d.mapgraph  is  the  same  as  that  erf  the  map  layer  displayed  in  the  active  display  frame  on  the  graphics 
monitor  (or  that  of  the  user's  current  region,  if  no  map  is  displayed). 

The  graphics  language  is  simple  and  uses  the  following  commands: 

ft  comment 

A  line  of  comment  which  is  ignored  in  the  processing, 
move  xpos  ypos 

The  current  location  is  updated  to  xpos  ypos  (where  these,  respectively,  are  the  easting  and 
northing  of  geographic  coordinates  stated  in  the  map  coordinate  system  of  the  user’s  current 
GRASS  location,  falling  within  the  current  region  and  active  frame).  If  unspecified  by  the 
user,  the  current  location  becomes  (0,0).  If,  as  most  likely,  the  point  (0,0)  falls  outside  of  the 
user's  current  region,  graphics  drawn  there  will  not  appear  in  the  graphics  frame. 

Note:  use  g.region  to  obtain  the  coordinates  of  current  location.  Use  d.where  to  obtain 
specific  map  coordinates  of  various  points  at  the  raster  map  displayed  in  the  active  frame. 

Note:  there  must  be  a  space  between  xpos  and  ypos. 
draw  xpos  ypos 

A  line  is  drawn  in  the  current  color  from  the  current  location  to  the  new  location  xpos  ypos, 
which  then  becomes  tlx:  current  location,  xpos  and  ypos  are  (respectively)  an  easting  and 


GRASS  4.0  (Summer  1991) 


U.S.  Armv  CliRl . 


45 


(.1  nvtpgraph 


(iRASS  Reference  Mamuil 


djnapgraph 


northing  stated  in  the  map  coordinate  system  of  the  user's  current  GRASS  location,  and  located 
within  the  user’s  current  geographic  region  and  active  frame. 

Note:  there  must  be  a  space  between  xpos  and  ypos. 

color  color 

Sets  the  current  color  to  that  stated.  Color  options  are.  red,  orange,  yellow,  green,  blue, 
indigo,  violet,  magenta,  brown,  gray,  white,  and  black. 
size  xper  yper 

Subsequent  text  will  be  drawn  such  that  the  text  is  xper  percent  of  the  display  frame’s  width 
and  yper  percent  of  the  display  frame  height.  If  not  specified  by  the  user,  the  text  size 
becomes  5%  of  the  active  frame’s  w  idth  and  5%  of  the  frame’s  height,  Ibis  is  equivalent  to 
entering  size  5  5. 
text  line-of-text 

The  stated  text  is  drawn  at  the  current  location  using  the  current  color  and  the  current  size, 
icon  type  size  x  y 

Draws  an  icon  of  types  o,  x,  or  +  with  specified  size  at  location  x.y.  Note:  type  o  designates 
a  square. 

polygon 

xpos  ypos 
xpos  ypos 


The  map  coordinates  appearing  on  lines  beneath  the  word  polygon,  one  pair  per  line, 
circumscribe  a  polygon  which  is  to  be  filled  with  the  current  color. 

NOTES 

d.mapgraph  is  identical  to  the  d-graph  command,  except  for  the  difference  in  coordinate  systems  used. 
d.mapgraph  will  complain  if  the  user  enters  something  to  standard  input  that  it  dies  not  understand. 
Blank  lines  in  the  input  file  will  result  in  this  error  message. 

SEE  ALSO 

d.INTRO,  d.frame,  d.graph,  d.rast,  d.zoom,  g.region,  grass. logo  jsh,  and  parser 
AUTHOR 

James  Westervelt,  U.S.  Army  Coast  met  ion  Fngincering  Research  laboratory 
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NAME 

djneasure  -  Measures  the  lengths  and  areas  of  features  drawn  by  the  user  in  the  active  display  frame 
on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

djneasure 
djneasure  help 

djneasure  [cl=name]  [c2  =name] 

DESCRIPTION 

djneasure  provides  the  user  with  an  interactive  way  to  measure  the  lengths  and  areas  erf  lines  and 
polygons  drawn  by  the  user  in  the  active  frame  on  the  graphics  monitor.  Lines  and  polygons  are  drawn 
using  a  pointing  device  (mouse).  Each  line  segment  is  drawn  in  colors  cl  and  c2.  A  mouse  button 
menu  indicates  that  the  user  can  find  out  the  geographic  coordinates  of  the  cursor  location,  draw  line 
segments  between  user-specified  vertices,  and  quit  d. measure.  Lines  and  polygons  are  defined  by  the 
series  of  vertices  marked  by  the  user.  If  more  than  two  successive  vertices  are  drawn,  djneasure  prints 
the  area  encompassed  (d.measure  will  assume  the  area  is  closed  even  if  the  user  has  not  joined  the  first 
and  last  vertices).  Line  lengths  are  stated  in  die  same  units  as  those  of  the  current  LOCATION.  Areas 
are  stated  in  hectares,  square  miles,  and  square  meters. 

lines  and  polygons  drawn  using  djneasure  will  overlay  (not  overwrite)  whatever  display  currently 
appears  in  the  active  frame  on  the  graphics  monitor.  The  user  can,  for  example,  run  drast  or  dvect 
prior  to  mnning  djneasure,  and  use  raster  and/or  vector  maps  as  a  backdrop. 

OPTIONS 

The  user  can  specify  the  colors  in  which  line  segments  will  be  drawn  by  setting  die  values  of  cl  and 
c2  on  the  command  line.  Default  line  colors  (see  below)  will  be  used  if  the  user  does  not  specify  the 
values  of  cl  and  c2  on  the  command  line. 

Parameters: 

cl  name  The  first  color  in  which  each  line  segment  is  drawn,  while  being  positioned. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  black 
Default:  white 

c2  name  The  second  color  in  which  each  line  segment  is  drawn,  after  its  vertices  are  fixed. 

Options:  Same  as  cl. 

Default:  white 

NOTES 

d.measure  uses  all  segments  drawn  by  the  user  when  computing  area.  If  the  user  draws  an  area  within 
another  area,  the  combined  area  of  both  regions  will  be  output. 

SEE  ALSO 

d.display,  d.frame,  d.graph,  d.mapgraph,  d.rast,  d.vect,  d.where 

AUTHOR 

James  Westervelt,  U.S.  Army  Constiuctiai  Engineering  Research  Laboratory 
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NAME 

d.menu  -  Creates  and  displays  a  man  within  the  active  frame  on  the  graphics  monitor. 

(GRASS  Display  Program  ' 

SYNOPSIS 

danenn 
d.menu  help 

d.menu  [bcolor  =name ]  [teolor =name\  [dcolor  =name]  [siz t=value] 

DESCRIPTION 

d.menu  allows  the  user  to  create  a  menu  containing  a  title  and  options,  and  to  display  this  menu  in  the 
active  frame  on  the  graphics  monitor.  After  the  menu  is  displayed  in  the  active  frame,  the  point!  nr 
device  (mouse)  is  activated  and  must  be  used  to  select  one  of  the  menu  options.  I  he  number 
associated  with  the  selected  menu  option  is  then  printed  to  standard  output  and  the  program  exits.  This 
program  provides  GRASS  macro  writers  with  a  mouse  interface  for  users. 

Parameters  can  be  stated  on  the  command  line,  from  within  standard  input,  or  (as  illustrated  in 
EXAMPLE)  from  within  a  script  file. 

The  user  can  specify  the  menu’s  background,  text,  and  line  colors  ( bcolor ,  teolor,  and  dcolor)  and  the 
menu  size  (size)  on  the  command  line.  If  the  user  sets  at  least  one  of  these  values  on  the  command 
line,  any  remaining  values  that  are  not  specified  on  the  command  line  will  be  set  (automatically)  to 
their  default  values  (see  below).  Alternately,  the  user  can  simply  type  danenn  on  the  command  line; 
in  this  case,  the  program  will  prompt  the  user  for  the  menu  colors  and  text  size  using  the  standard 
GRASS  parser  interface  described  in  the  manual  entry  for  parser.  The  user  will  then  be  (silently) 
prompted  to  enter  the  menu’s  location  and  contents  through  standard  input  (see  Menu  Information, 
below). 


Parameters: 
bcolor  name 


teolor  name 


dcolor  =name 


mz  e=value 


Sets  the  color  of  the  menu  background  (the  rectangle  on  which  the  text  sits). 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  black. 

Default:  black 

Sets  the  color  of  the  menu  text. 

Options:  Same  as  those  for  bcolor. 

Default:  white 

Sets  the  line  color  used  to  divide  text  lines  in  the  menu. 

Options:  Same  as  those  for  bcolor. 

IMault:  white 

Sets  the  menu’s  text  size  to  the  specified  value.  Sizes  are  stated  as  percentages  of 
the  height  of  the  active  g rapines  display  frame. 

Options:  1  -  100 
Default:  3  (i.e.,3%) 


Menu  Information: 

After  the  user  has  (optionally)  specified  menu  colors  and  size,  the  program  expats  the  user  to  enter 
information  about  the  menu’s  location  and  content.  The  menu  w'ill  be  placed  in  the  lower  left  comer  of 
the  active  display  frame  by  default  if  the  user  does  not  position  it  elsewhere  using  the  T  or  .1, 
commands. 

The  user  specifies  the  menu  contents  by  typing  in  a  menu  title  followed  by  the  option  choices  to  appear 
in  the  menu  when  displayed.  The  user  must  enter  a  menu  title  and  at  least  one  menu  option. 
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•T  value  Specifies  the  menu’s  distance  from  the  active  display  frame’s  top  edge  (as  a 

percentage  of  the  active  frame’s  height). 

Note:  Not  required 

X  value  Specifies  the  menu’s  distance  from  the  active  display  frame’s  left  edge  (as  a 

percentage  of  the  active  frame’s  width). 

Note:  Not  required 

menu  title  A  title  that  describes  the  type  of  options  listed  in  the  menu,  and  that  will  appear  at 

the  top  of  the  menu  when  it  is  displayed. 

option  name( s)  The  options  that  will  appear  in  the  menu  when  displayed.  Each  menu  option  should 

appear  on  a  separate  line.  The  user  may  otter  as  many  options  as  desired,  but  must 
enter  at  least  one  menu  option. 

Note:  The  user  should  choose  a  menu  size  and  location  that  will  allow  all  menu 
options  to  be  displayed  in  the  active  frame. 

If  the  user  enters  the  menu  title  and  options)  from  standard  input  (i.e.,  at  the  keyboard  rather  than  from 
a  file),  the  user  should  enter  control-d  to  end  input  and  display  the  menu  in  the  active  frame  on  the 
graphics  monitor.  (Note:  The  eLmenu  program  can  also  be  incorporated  into  UNIX  Bourne  shell  script 
macros.  The  below  example  shows  how  this  might  be  done.) 

EXAMPLE 

hi  the  following  example,  the  shell  script  menu2  calls  the  shell  script  color  select,  which  contains 
d.menu  commands  to  display  a  menu  in  the  current  frame  on  the  graphics  monitor.  After  the  user 
selects  an  option  from  the  display  menu,  the  selection  number  is  available  for  use  by  menu2. 

Contents  of  file  menu2  . 

&  foin/csh  -f 
set  option  —  0 

set  colors  =  (red  green  blue  black  white  ) 

@  option  — '  color  jselect' 

if  (S option  <=  5)  then 

set  color  =  ScolorsfSoption] 
echo  S color 

endif 

exit 

Contents  of  file  color  jselect'. 

HI  fbinJcsh  -f 

d.menu  bcolor  =red  t color  =grcen  dcalor  =yellow  size  =5  «EOF 
.T  25 
.L25 

Color  Choices 
Option  1 
Option  2 
Option  3 
Option  4 
Option  5 
EOF 

If  the  user  runs  menu2,  a  menu  will  be  displayed  on  the  graphics  monitor  that  has  red  background, 
green  text,  with  mem  options  divided  by  yellow  lines,  and  a  text  size  erf  5%  of  the  active  cfisplay  frame 
height.  The  mouse  cursor  will  become  active,  allowing  the  user  to  select  (by  pointing  with  the  mouse) 
one  of  the  displayed  menu  options.  Here,  these  menu  options  are  called  Option  1,  Option  2,  and 
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Option  3,  etc.  The  first  line  of  text  (here,  the  words  Color  Choices)  contains  the  title  of  the  menu; 
this  line  is  not  a  menu  option  that  can  be  chosen  by  the  user  with  the  mouse.  When  the  user  presses 
one  of  the  mouse  buttons  while  pointing  to  the  desired  menu  choice,  the  number  of  the  option  chosen 
will  be  available  for  capture  by  the  shell  script  menu2.  menu2  is  a  simple  example  that  takes  this 
information  and  only  echoes  it  to  the  screen. 

NOTES 

Although  the  user  can  vary  text  size,  all  text  within  the  same  menu  is  displayed  in  a  single  text  size 
(and  font).  If  the  user  specifies  that  items  included  in  the  menu’s  text  be  displayed  in  different  sizes, 
all  text  will  be  displayed  in  the  size  stated  last. 

SEE  ALSO 

d.display,  d.font,  d.frame,  d.grid  cLlabel,  d.legend  d.paint. labels,  <Ltext,  dJitle,  show.fonisjsh  and 
parser 

AUTHOR 

Janies  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.mon  -  To  establish  and  control  use  of  a  graphics  display  monitor. 

('GRASS  Display  Program) 

SYNOPSIS 

dan  on 
d.mon  help 

d.mon  [-ILprs]  [start  =name]  [stop  =name]  [select  =name]  [unlock  =name] 

DESCRIPTION 

The  GRASS  program  djnon  allows  the  user  to  start,  select,  list,  query  the  status  of,  release  control  of, 
stop,  and  unlock  control  of,  available  graphics  monitors.  The  user  can  run  this  program  either 
interactively  (through  a  series  of  menus),  or  non- interactively  by  typing  the  name  of  the  monitor  to 
start,  stop,  select,  or  unlock,  and  any  desired  flags  on  the  command  line. 

Flags: 

-I  List  all  monitors 

-L  list  all  monitors  (with  current  status) 

-p  Print  name  of  currently  selected  monitor 

-r  Release  currently  selected  monitor 

-s  Do  not  automatically  select  when  starting 

Parameters: 

start  name  Name  of  graphics  monitor  to  start 
tAap=name  Name  of  graphics  monitor  to  stop 
select  name  Name  of  graphics  monitor  to  select 
unlock  name  Name  of  graphics  monitor  to  unlock 

When  the  user  enters  the  command  daman  without  specifying  parameter  values, 
the  below  menu  appears  on  the  screen: 

MONITOR  MENU 

Making  sure  that  the  graphics  monitor  is  running: 

1  -  Start  a  graphics  monitor 

(also  automatically  selects  this  monitor) 

2  -  Stop  a  graphics  monitor 

Choosing  a  graphics  monitor  for  your  graphics: 

3  -  Select  a  graphics  device  for  output 
(currently  selected  monitor:  name) 

4  -  Release  control  of  the  graphics  driver 
(let  someone  else  use  it) 

(option  4  appears  only  after  selection  of  a  monitor) 

RETURN  quit 
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Iliese  parameters  perform  the  following  functions: 

1  Start  a  Monitor. 

hi  order  to  display  on-screen  GRASS  graphics,  the  user  must  start  and  select  a  graphics  monitor. 
By  default,  the  start  command  actually  runs  two  commands,  to  both  start  and  select  whatever 
monitor  is  named  by  the  user.  (The  user  can  get  a  list  of  available  monitors  by  setting  the  -1  or  -L 
flag  on  the  command  line.) 

When  a  monitor  is  started ,  it  is  therefore  also  (automatically)  selected  for  output,  unless  the  -s 
flag  is  set  by  the  user;  the  user  can  also  explictly  select  a  monitor  that  has  beat  started  (see  (3) 
below).  After  a  monitor  is  started,  a  blank  graphics  frame  should  appear  on  whatever  terminal  the 
user  is  using  to  display  graphics. 

'Hie  desired  monitor  should  be  started  once  and  need  not  be  restarted  unless  it  is  stopped  (option 
2)  for  some  reason.  A  monitor  may  continue  to  run  for  any  length  of  time,  even  when  no  GRASS 
session  is  being  nut.  The  monitor  program  runs  in  the  background. 

2  Stop  a  Monitor. 

Sometimes  the  monitor  program  needs  to  be  stopped  (terminated).  Choosing  option  2  will 
terminate  a  user-specified  monitor  program. 

A  graphics  monitor  has  two  different  types  of  status:  monitor  program  not  running,  and  monitor 
running.  A  monitor  that  has  been  started  and/or  selected  will  be  listed  as  running;  a  monitor  that 
hits  been  stopped  (or  not  started)  will  be  listed  as  not  ntnning.  The  -L  (list  status)  flag  will  list  the 
status  of  each  monitor  connected  to  the  system. 

3  Select  a  Monitor. 

When  the  user  starts  a  monitor,  it  is  also  (automatically)  selected  for  graphics  output  unless  the 
user  sets  the  -s  flag.  In  order  to  use  (direct  graphics  output  to)  a  monitor,  the  user  must  select  that 
monitor  for  use,  either  by  simply  starting  the  monitor  without  the  -s  flag  or  by  cxphctlv  selecting 
the  monitor  for  output  using  option  3.  Only  running  monitors  can  be  selected  for  graphics  output. 
Once  the  user  has  selected  a  monitor  for  output,  no  other  user  can  use  this  monitor  for  graphics 
output  imtil  the  monitor  driver  is  either  released  (by  flic  user)  or  unlocked  (bv  ;tny  user  on  the 
system). 

Tlie  user  can  nm  multiple  graphics  monitors  by  simply  starting  each  of  flic  graphics  monitors 
drivers  he  wishes  to  direct  output  to. 

4  Release  a  Monitor. 

Once  a  user  lias  selected  a  monitor  for  graphics  output,  it  is  locked  for  use  by  that  user  until 
either:  (1)  the  user  voluntarily  releases  control  of  the  monitor  for  use  by  another  (option  4).  or  (2) 
another  GRASS  user  unlock s  the  user’s  control  of  the  monitor.  Menu  option  4  appears  only  to  the 
person  who  has  selected  the  monitor  (since  only  that  user  can  release  control  of  his  selected 
graphics  monitor.)  If  another  user  wishes  to  unlock  the  user’s  control  of  the  monitor,  that  user 
must  nm  d.mon  from  the  comniiuid  line  and  set  tlie  unlock  -=name  parameter. 

You  may  choose  multiple  options  within  the  d.mon  program.  To  leave  (exit)  the  d.mon  menu,  press 
the  <Ri:HJRN>key. 

NOTES 

Hie  d.mon  program  can  regulate  control  of  graphics  monitors  Ixith  in  systems  using  multiple  monitors 
and  in  systems  using  a  single  graphics  monitor. 

SEE  ALSO 

d. erase,  d.frame,  monitorcap 

AUTHOR 

Michael  Shapiro.  U.S.  Army  Consimclion  I -ng  meeting  Research  laboratory 
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NAME 

d.paint. labels  -  Displays  text  labels  formatted  for  use  with  GRASS  paint  ip  labels,  pjrtap )  output  to 
the  active  frame  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.paint.labels 
d.paint  .labels  help 
d.paint.labels  6le=name 

DESCRIPTION 

d.paint. labels  displays  the  paint  label  hie  name  in  the  active  display  frame  on  the  graphics  monitor. 
This  hie  can  be  generated  by  the  labels  option  in  the  plabels  program,  the  d. labels  program,  or 
amply  created  by  the  user  as  an  ASCII  hie  (using  a  text  editor  like  vi)  and  placed  in  the  appropriate 
/paint/labels  directory  under  the  user’s  current  mapset  and  location 
(i.e.,  under  SLOCATION/paint/labels). 

OPTIONS 

Parameter: 

fUe=name  Name  of  ASCII  hie  containing  paint  labels. 

This  program  can  be  run  either  non-interactively  or  interactively.  If  the  user  specifies  the  name  of  a 
paint  labels  hie  cm  the  command  line,  the  program  will  run  without  interacting  with  the  user. 
Alternately,  the  user  can  type  simply  d.paintJabels  on  the  command  line;  in  this  case,  the  program 
will  prompt  the  user  for  the  name  of  a  paint  labels  hie  using  the  standard  GRASS  parser  interface 
described  in  the  manual  entry  for  parser. 

NOTES 

Some  of  the  information  stored  in  die  label  file  is  unused  by  tLpaint. labels.  The  unused  information 
found  in  a  label  hie  is  printed  to  standard  output.  This  extra  inf  on  nation  is  used  by  such  programs  as 
p.labels  and  pjnap. 

SEE  ALSO 

d.display,  <Lfont,  dlabel,  dlabels,  dLtext,  d. title,  plabels,  pjnap  and  parser 
AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.points  -  Displays  point  graphics  in  the  active  frame  on  the  graphics  display  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d^Mxnts 
({.points  help 

d.points  [color  =name]  [sz e=value]  [typ e=name\  ^ &\e=name ] 

DESCRIPTION 

cLpoints  dismays  points  whose  coordinate  locations  are  specified  by  the  user  and  located  within  the 
current  geographic  region  in  the  active  display  frame  on  the  graphics  monitor.  Point  coordinates  are 
read  either  from  standard  input  or  from  a  file  stated  dy  the  file  =name  option.  When  entering 
coordinates  through  standard  input,  the  user  presses  contru'.-d  to  signal  the  end  of  input  to  d.points. 

The  program  can  be  run  interactively  or  non- interactively.  The  user  can  run  the  program  completely 
non-interactively  by  specifying  the  name  of  a  points  file  (containing  the  geographic  coordinates  of  icons 
to  be  sited)  and  the  values  of  all  needed  parameters  on  the  command  line.  If  the  name  of  an  input  file 
to  d.points  is  given  on  the  command  line,  any  other  parameter  values  left  unspecified  on  the  command 
line  (e.g.,  the  icon  color,  size,  and/or  type)  arc  set  to  their  default  values. 

The  user  can  instead  elect  to  run  the  program  partially  interactively,  by  specifying  any  /all  of  the 
parameters  except  the  points  fi\e=name  parameter  on  the  command  line.  In  this  case,  d.points  will 
expect  the  user  to  enter  icon  locations  from  standard  input  (i.e.,  at  the  keyboard)  and  will  (silently) 
prompt  the  user  for  these  locations,  bach  icon  location  should  be  entered  as  an  easting  and  northing 
pair  separated  by  a  space,  followed  by  i  carriage  return.  Qxrdinates  slxxild  be  stated  in  whatever  map 
coordinate  system  is  used  by  the  user’s  current  GRASS  location.  The  user  presses  control-d  to  signal 
the  end  of  standard  input  to  d.points. 

Alternately,  the  user  can  simply  type  d .points  on  the  command  line,  ;uid  Ire  prompted  for  the  values  of 
all  parameters  (the  user  can  still  input  icon  emmli  nates  from  an  input  tile  using  this  form).  In  this  case, 
the  user  is  presented  with  the  standard  GRASS  parser  it.  erface  described  in  the  manual  entry  for 
parser. 

Parameters: 

color  =name  Sets  the  current  color  to  the  name  stated. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  white,  and  black 
Default:  gray 

size  =value  Size  of  icon  in  pixels. 

Options:  0-1000  (jiixcls) 

Default:  5  (pixels) 

type  name  Sets  the  shape  (tyjtc)  of  the  icon  to  be  drawn  to  name. 

Options:  x,  diamond,  box,  + 

Default:  + 

file  name  lake  input  from  the  UNIX  lile  name.  (Note:  This  file  must  be  in  the  user's  current 
directory  (T  given  by  its  full  path  name.) 

Default:  Standard  input. 

The  file  contents  should  consist  of  a  series  ol  geographic  coordinates  that  lit  within  the 
boundaries  of  the  current  geographic  region  falling  within  the  active  display  frame  'refer 
to  d.where  or  g. region  for  these  coc  linates).  l-ach  icon  location  slxxild  lie  specified 
by  an  easting  and  northing  (in  tint  order)  separated  by  a  single  blank  space,  ami 
followed  by  a  carriage  return,  bastings  and  nortliings  sIkxiIci  oe  stated  in  whatever  map 
coordinate  system  is  being  used  by  the  user’s  current  GRASS  location. 
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NOTES 

d.points  will  display  a  point  at  the  location  specified  in  the  active  frame,  even  if  the  point  lies  outside 
the  boundaries  of  current  geographic  region. 

SEE  ALSO 

d.frame,  d.where,  d.siies,  g.region,  s. out. ascii,  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Gins t ruction  Engineering  Research  Laboratory 
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NAME 

d.profde  -  Displays  profiles  of  a  user- specified  rasler  map  layer. 

(GRASS  Display  Program) 

SYNOPSIS 

d.  profile 

DESCRIPTION 

This  command  works  only  interactively.  It  clears  the  entire  graphics  screen  and  provides  a  grapliical 
interaction  allowing  the  selection  of  transects  for  which  profiles  are  then  generated. 

USER  PROMPTS 

first,  you  will  be  presented  with  a  prompt  asking  you  to  choose  a  raster  map  layer  to  be  profiled.  Once 
you  specify  a  valid  raster  map  layer  name,  the  map  layer  will  be  displayed  in  the  left  half  of  the 
graphics  display,  and  the  right  half  of  the  dispay  will  be  divided  into  four  display  frames.  There  will 
also  be  two  frames  along  the  top  of  the  display:  a  mouse-button  menu  frame  on  the  left,  and  a  status 
frame  on  the  right. 

The  mouse-button  menu  initially  offers  you  three  options: 

Mouse  Buttons: 

Left:  Where  am  I? 

Middle:  Mark  FIRST  Point  of  Profile  Line. 

Right:  QUIT  this. 

You  may  query  the  displayed  raster  map  layer  by  indicating  points  with  the  left  mouse-button.  The 
coordinates  atxl  category'  value  of  each  point  that  you  indicate  will  be  displayed  on  in  the  status  fr.une. 
If  you  mark  the  first  point  of  the  profile  line  you  will  lie  presented  with  the  following  mouse-lxitton 
menu: 


Mtxisc  Buttons: 

left:  Where  am  I? 

Middle:  Mark  SECOND  Point  of  Profile  Line. 

Right:  QUIT  this. 

( )nce  you  mark  the  second  point  of  the  profile  line,  the  profile  line  will  lie  lalxTed  (with  a  letter  from  A 
to  I))  and  displayed  in  one  of  the  four  display  frames  on  the  right  hand  side  of  the  screen.  You  will 
then  lie  presented  with  a  third  mouse-button  menu: 

Mouse  Buttons: 
left:  IX)  ANOI  HLR 

Middle:  CLIiAR  DISPLAY 

Right:  QUIT  this. 

II  you  would  like  to  view  ; mother  profile,  click  on  tlx1  left  mouse  button.  II  you  would  1  ike-  to  redisplay 
the  raster  map  layer  ;uid  cle;ir  out  the  four  profile  frames,  click  on  tlx  middle  mouse  button.  II  you 
would  like  to  quit,  then  click  on  the  right  Ixitton. 

NOTES 

I  sc  fill  enhancements  to  d. profile  would  include: 

I I  Adding  an  option  to  display  profiles  using  category  colors,  like  a  bar  chart. 

2)  Allowing  profile  lines  to  lx:  defined  bv  a  series  of  points,  not  just  two. 

')  Allowing  {trollies  to  lx:  saved  in  a  file,  for  later  viewing. 

»)  Allowing  the  user  to  enter  profile  line  jxxnts  bv  tvping  coordinates. 
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NAMK 

d.rast  -  Displays  and  overlays  raster  map  layers  in  the  active  display  frame  on  the  graphics  monitor. 
(GRASS  Display  Program) 

SYNOPSIS 

dxast 

d.rast  help 

d.rast  [-o]  map  name 


DESCRIPTION 

d.rast  displays  the  raster  map  layer  name  in  the  active  display  frame  at  the  grapliics  monitor. 

The  program  can  be  run  either  non- interactively  or  interactively.  If  the  user  specilies  the  name  of  a 
raster  map  layer  (map -name)  and  (optionally)  the  -o  option  on  the  command  line,  the  program  will  nut 
non-interactively.  Alternately,  the  user  can  type  simply  d.rast  on  the  command  line;  in  this  case,  the 
program  will  prompt  the  user  for  the  flag  setting  and  parameter  value  using  the  standard  (JRASS  parser 
interface  described  in  the  manual  entry  for  parser. 

Flag: 

-o  Overlay  the  named  raster  map  layer  onto  whatever  is  already  displayed  in  the  active 

graphics  frame.  Any  zero  category  value  data  areas  in  the  named  raster  map  will  seem 
transparent,  and  reveal  the  underlying  image  previously  displayed  in  the  graphics  frame. 
If  the  -o  flag  is  set,  only  cells  containing  non-zero  category  values  will  be  display  ed 
from  the  overlaid  raster  map.  All  other  areas  (i.e.,  the  portions  of  the  overlaid  map 
that  contain  category  value  zero)  will  leave  the  underlying  display  untouched.  If  the  -o 
flag  is  not  set  by  the  user,  d.rast  will  (by'  default)  completely  overwrite  whatever 
appears  in  the  active  graphics  display  frame. 


Parameter: 

map  name  Name  of  the  raster  map  to  be  displayed.  If  the  active  graphics  frame  a] ready  contains 
text  or  graphics,  and  the  user  does  not  wish  to  use  the  -o  option,  it  is  wise  to  first 
invoke  d.erase  to  clear  the  active  graphics  frame  before  miming  d.rast.  After  naming 
d.rast,  other  d.  prognuns  like  d.vec.l  and  d.gnd  can  lx.-  used  to  enhance  the  plot. 

NOTES 

Ihe  d.rast  raster  map  overlay  option  (o)  only  works  when  the  color  look-up  table  for  the  graphics 
monitor  is  set  to  d. colormode  fixed. 

SEE  ALSO 

d.choose,  d.  col  or  mode,  d.colors,  d.colortable,  d.display,  d.erase,  d.grid,  d.werlay,  d.vect, 
d.what.rast,  r. reclass,  and  parser 

AUTHOR 

Janies  Westervclt,  US.  Army  (ions!  rue  lion  ling  meeting  Research  lulioratorv 
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NAME 

d.rast Arrow  -  Draws  arrows  representing  cell  aspect  direction  for  a  raster  map  layer. 

(GRASS  Display  Program) 

SYNOPSIS 

d^astjurrow 
d.rast  .arrow  help 

dxastjrrow  [map  =name]  [type  =name]  [arrow  color  name]  [gridcolor^ name] 

{ x  color  name ]  [unknown  color  name] 

DESCRIPTION 

d.rast Arrow  is  designed  to  help  users  better  visualize  surface  water  flew  direction,  as  indicated  in  an 
aspect  raster  map  layer.  There  are  two  ways  to  specify  the  aspect  layer  the  program  is  to  use.  Ihe  first 
is  to  display  the  aspect  map  layer  at  the  graphics  monitor  before  mnning  d.rast  .arrow .  The  second 
method  involves  setting  the  map  parameter  to  the  name  of  the  desired  aspect  map.  This  allows  the 
arrows  to  be  drawn  over  any  other  maps  already  displayed  on  the  graphics  monitor. 

d.rast.arrow  will  draw  an  arrow  over  each  displayed  cell  to  indicate  in  which  direction  the  cell  slopes. 
An  arrow  can  point  in  one  of  eight  directions.  If  the  aspect  layer  has  a  category  value  denoting 
locations  of  "unknown"  aspect,  drast  Arrow  draws  a  question  mark  over  the  displayed  cells  of  that 
category.  Cells  of  category  0  (no  data)  will  be  marked  with  an  "X". 

COMMAND  LINE  OPTIONS 
Parameters: 

map  name  Name  of  an  existing  raster  map  layer  to  be  displayed. 

typ *=name  Type  of  existing  raster  data  to  be  displayed. 

Options:  grass,  agnps,  answers 
Default:  grass 

Using  this  information,  drast. arrow  uses  internal  information  to  convert  category 
values  into  appropriate  arrow  directions. 

arrow_col«r  =name 

Color  in  which  ;irrows  will  be  drawn. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown, 
gray,  black 
Default:  green 

grid_coiar  =name  Color  in  which  grid  outlines  will  be  drawn. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown, 
gray,  Hack 
Default:  gray 

x.  color  =name  Color  in  which  x’s  will  be  drawn. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown, 
gray,  Hack 
Default:  white 

unknowncolor  =name 

Color  in  which  unknown  information  will  be  displayed. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown, 
gray,  black 
Default:  red 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  src.;ilpha  directory  and  must  be  compiled 
separately  liy  the  user. 
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SEE  ALSO 

d.frame,  d.rast,  d.rast.edit,  d.rast.num,  d.rast.z<xm,  d.zoom,  g.region,  r.mask,  rjlope. aspect,  and 
parser 

AUTHOR 

Chris  Rewerts  (rewerts@ecn.purdue.edu),  Agricultural  Engineering,  Purdue  University. 
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NAME 

d.rast.edit  -  Program  allowing  users  to  interactively  edit  the  cell  category  values  of  raster  map  layers 
displayed  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

djast^dit 

d .rust -edit  help 

d-rast.edit  [  grid_color  =name  \ 

DESCRIPTION 

The  d.rast.edit  program  allows  users  to  interactively  edit  cell  category  values  in  a  raster  map  layer 
displayed  to  the  graphics  monitor  using  a  mouse  cursor.  This  program  determines  the  name  of  the 
raster  map  layer  currently  displayed  in  the  active  frame  on  the  selected  graphics  monitor  (if  none, 
program  will  abort).  The  user  is  then  prompted  for  the  name  of  a  new  raster  layer  to  be  created  in  his 
mapset.  d-rast.edit  does  not  modify  the  user’s  original  raster  map  layer. 

OPTIONS 

Parameter: 

grid__coIor  =color  Sets  the  color  to  be  used  for  a  grid  drawn  during  edit  mode.  A  well-selected  grid 

color  helps  to  identify  individual  cells  in  the  output. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  white,  and  black 
Default:  black 

Geographic  Region  Concerns 

d.rast.edit  reads  the  region  definition  for  the  raster  map  layer  being  euited  from  its  cell  header  file. 
The  new,  edited  copy  of  the  raster  layer  will  be  created  with  the  same  resolution  and  region 
dimensions.  If  the  current  region  resolution  does  not  match  the  raster  map  layer’s  resolution,  the 
program  will  abort.  The  north,  south,  east,  and  west  geographic  region  settings  of  the  current  region 
can  be  set  to  any  view,  as  long  as  they  fall  within  the  boundaries  of  the  raster  map  layer  described  in 
its  cell  header.  Ihis  is  important,  since  the  current  view  must  be  such  that  individual  cell  locations  are 
easily  visible  and  sufficiently  large  on  the  graphics  monitor  to  be  pointed  at  with  die  mouse  cursor. 
Any  mask  in  place  will  lie  ignored  when  writing  the  new  raster  map  layer. 

Mouse  Menus 

Cell  editing  is  done  using  a  mouse  cursor  to  choose  menu  selections  and  indicate  areas  on  the  displayed 
raster  map  that  arc  to  be  edited. 

Main  Menu  options  and  subsequent  functions  and  sub-menus  are  described  below: 

1)  Edit 

invokes  edit  mode,  during  which  no  graphic  menus  are  used,  so  that  none  of  the  displayed  map  is 
hidden.  At  the  start  of  the  edit  mode,  a  grid  is  drawn  over  displayed  cells  to  help  distinguish  cell 
Ixxuularics.  Users  can  select  the  color  of  this  grid  by  setting  the  grid_color  parameter.  Interaction 
with  tlx:  program  during  edit  nxxle  is  done  by  using  the  three  mouse  buttons  as  follows: 

left  Button 

what’s  here.  Identify  the  category  value  of  the  cell  under  the  mouse  cursor  when  the 
button  is  pressed.  The  category  value  of  this  cell  is  printed  in  the  text  frame. 

Middle  Button 

edit.  Hie  current  category  value  of  the  cell  under  the  mouse  cursor  is  iterated  and  a 
prompt  for  a  new  cell  value  appears  on  the  textual  command  fnune.  (Reniemlier  to 
move  tlx:  nxxisc  to  the  text  frame),  latter  a  new  cell  category  value  that  is  within  tlx: 
range  of  current  category  values  for  the  map  layer.  Note:  the  edited  cell  is  ilisplaycd 
in  the  color  of  tlx:  newly  assigixxl  category  value,  but  is  hatched  with  lines  of  the  grid 
color  to  indicate  it  has  been  edited,  since,  if  the  value  of  the  cell  is  filled  (Ixriore 
leaving  edit  nxxle).  tlx-  old  category  value  will  be  reported. 
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Right  Button 

exit  edit  mode.  Command  is  returned  to  the  Main  Menu  on  the  graphics  monitor. 
If  cell  value  changes  were  made  during  edit  mode,  the\'  will  lx-  saved  upon  exit. 

2)  Redraw 

redisplays  the  raster  map  layer  on  the  graphics  monitor. 

3)  Zoom 

calls  the  d.rast.zoom  program,  to  allow  changing  the  view  of  the  raster  layer.  Zoom’s  instnictions 
will  appear  on  the  text  command  window.  Interaction  is  conducted  using  mouse  kevs. 

4)  Arrow 

Ibis  function  is  available  for  users  editing  aspect  maps.  I  lie  d.rast. arrow  prog  nun  is  called,  which 
ilraws  arrows  over  the  displayed  cells  to  indicate  the  downslojv  direction  of  the  cell.  After  selecting 
the  arrow  selection  from  the  m;iin  menu.  sub- menus  will  appear,  allowing  input  options  to  lx-  set  for 
the  d.rast. arrow  program.  'Ihe  first  sub- menu  selects  the  type  of  aspect  ilata  displaved  (regular 
"GRASS"  fonnat,  as  prcxlueed  by  r. slope  aspect',  a  format  prepared  as  iiijxit  to  the  "  A(  iNPS"  program: 
;md  a  fonnat  prepared  for  the  "ANSWERS"  program).  Ihe  d.rast. arrow  program  can  accept  the  name 
ol  a  layer  not  drawn  on  the  display  for  use  as  input.  and  an  option  is  given  to  in|xit  the  name  of  tliat 
layer,  if  desired.  Otherwise,  the  currently  displayed  map  layer  will  lx-  used.  Next,  the  color  options  of 
d.rast. arrow  may  lx-  set  via  separate  menus,  ora  choice  for  using  default  sellings  may  lx-  used. 

5 )  Number 

calls  the  j.rast.num  prog  nun,  which  will  print  die  cell  category  values  over  the  displayed  cells  on  the 
graphic  monitor. 

6)  Options 

change  the  program  options  setting  for  grid.color . 

1)  Exit 

quit  the  d.rast.edit  program.  If  edits  have  been  made,  the  new  raster  map  layer  will  lx  created. 
Support  files  are  constructed.  Category  lalx-ls  and  color  maps  (if  any)  ;ire  copied  Irom  the  original 
layer,  d.rast. edit  redisplay  s  the  original  raster  map  tile  on  the  monitor  as  it  exits. 

NOTKS 

d.rast.edit  will  not  create  a  txvv  raster  map  layer  it  the  user  makes  no  cell  edits  while  miming  the 
program. 

Ik  cureful  not  to  cover  the  graphics  monitor  window  w  ith  anotlier  frame  during  the  editing  pnxvss.  In 
some  eases,  the  redraw  option  will  lx  able  to  remov  e  traces  of  other  frames;  otherwise,  tlx-  graphics 
monitor  will  not  lx  refreshed  until  after  d.rast.edit  exits,  further  note,  however,  tliat  this  lias  only 
Ixen  tested  on  SUN  workstations,  using  a  hick  lifted  SlJNVil-W  grajihics  monitor  driver. 

Ihe  primary  banc  of  the  d.rast.edit  program  involv  es  large  map  lay  ers  (with  lots  of  row  s  and  columns) 
und/or  slow  computers,  since  the  program  must  read  and  w  rite  raster  map  lay  ers  row  by  row  for  the  full 
size  of  the  map  layer  as  dictated  by  its  region  size  and  resolution.  (  Ilie  current  region  sellings  of  north, 
south,  ea  t,  and  west  will  not  limit  the  size  of  the  edited  copy  of  the  map  layer,  since  by  use  of  the 
d.rast.zoom  program,  these  values  may  change  several  tinx-s  during  the  editing  session).  Ilicir  effects 
could  lx  lessened  if  the  program  were  to  create  a  table  of  changes  that  it  could  iixorjximlc  into  tlx-  new 
raster  lile  on  a  forked  process  started  when  the  user  exits,  or  otherwise  allow  the  user  to  issue  a  “save” 
command  when  the  user  has  made  all  desired  edits  to  tlx  raster  lile.  Currcntlv,  lor  instance,  if  the  user 
needs  to  use  d.rast.zoom  to  access  a  different  area  ol  the  map.  the  user  must  wait  for  a  read  and  write 
for  each  entrance  and  egress  of  the  edit  nxxlc. 

I  here  is  no  "undo"  command  or  way  to  exit  edit  nuxle  without  saving  cliangcs. 

It  vwxild  be  nice  to  incorporate  a  scrollable  version  of  d.legend  (such  that  one  could  see  a  legend  lor 
liles  with  many  categories  on  a  standard  size  subframe).  It  would  lx-  even  nicer  to  lx-  able  to  select 
the  category  values  from  a  graphical  legend  when  editing  cell  values  (tlicrcliv  saving  a  trip  to  the  text 
frame  to  type  in  the  new  v  alue). 
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Perhaps  method(s)  for  multiple  or  mass  cell  edits  would  be  useful.  This  could  be  done  by  providing 
modes  in  which  the  user  may:  1)  edit  a  block  of  cells  to  a  given  value  by  drawing  a  bcoc;  2)  be  able  to 
choose  a  given  value  that  then  is  automatically  used  as  the  new  value  for  each  cell  chosen  until  a 
different  value  is  desired. 

I  he  re  is  no  interrupt  handling.  This  could  leave  files  in  tmp  or  (rarely)  result  in  half-baked  raster  files. 
The  original  file  would  survive  imscathed  by  an  interrupt  at  most  arty  point  in  execution,  but  the 
graphics  monitor  may  be  left  in  an  indeterminate  state  (try  d.erase  ardjnon  select  =monitor _name  to 
bring  it  back  into  shape).  Beware  of  exiting  the  program  by  means  other  than  using  exit  on  the  Main 
Menu. 

Perhaps  a  grid_color  option  allowing  the  grid  to  lie  turned  off  is  needed,  since  it  may  be 
inappropriately  displayed  (i.e.,  not  over  the  cell  edges)  in  some  circumstances. 

The  program  has  no  method  to  enter  new  values  beyond  the  current  range  of  categories,  but  additional 
programming  could  make  it  so. 

This  program  remains  under  alpha  testiix;.  It  resides  in  the  src.alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

d.erase,  d.frame,  d.mon,  d.rast,  d.rast.arrow,  d.rast.num,  d.rastjzoom,  cLzoom,  g.region,  r.mask, 
and  r Mope. aspect 

AUTHOR 

Chris  Rewerts  (rewerts@ecn.purdue.edu),  Agricultural  Engineering,  Purdue  University.  June  1991. 
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NAME 

d.rastJium  -  Overlays  cell  category  values  on  a  raster  map  layer  dismayed  to  the  graphics  monitor. 
(GRASS  Display  Program) 

SYNOPSIS 

djastjium 
djastjium  help 

d.rast  .nuni  [map=name\  [grid  color  name] 

DESCRIPTION 

d.rast.num  overlays  cell  category  values  onto  a  raster  map  layer  displayed  to  the  user's  graphics 
monitor.  Category  values  will  be  displayed  in  white  and/or  black,  based  on  the  colors  in  which 
undedying  cells  are  displayed.  A  grid  outlining  each  map  cell  will  also  be  overlain  in  a  user-specified 
color. 

The  user  should  run  d.rast  to  display  the  desired  map  layer  on  the  graphics  monitor  before  nmning  this 
program. 

d.rast.num  can  be  run  non-interactively  or  interactively.  If  the  user  specifies  the  map  whose  category 
values  are  to  Ire  displayed  and/or  the  grid  color  on  the  command  line,  the  program  will  mn  non- 
interactively.  Alternately,  the  user  may  simply  type  dj-ast-nuni  on  the  command  line;  in  this  case,  the 
program  will  prompt  the  user  for  parameter  values  using  the  standard  GRASS  user  interface  described 
in  the  manual  entry  for  parser.  If  no  grid  color  is  given  the  default  will  be  used.  If  no  map  layer  is 
specified,  the  program  will  use  whatever  raster  map  layer  is  currently  displayed  in  the  active  frame  on 
the  graphics  monitor. 

COMMAND  LINE  OPTIONS 
Parameters: 

map  =name  Name  of  existing  raster  map  layer  whose  category  values  will  be  displayed. 

Default:  (whatever  raster  map  layer  is  currently  displayed) 

grid_color  =name  Color  in  which  an  overlain  grid  will  be  displayed. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown, 
gray,  black 
Default:  gray 

NOTES 

[he  user  is  advised  to  set  the  current  region  to  a  relativ  ely  small  area  (i.e.,  less  than  1(K)  rows  by  1 00 
columns);  otherwise,  the  individual  cells  being  displayed  will  be  small  and  the  category  value 
associated  with  each  will  be  difficult  to  see. 

Ibis  program  remaias  under  alpha  testing.  It  resides  in  the  sre .alpha  directory  anti  must  lie  compiled 
separately  by  the  user. 

SEE  ALSO 

d.erase,  d.frame,  d.grid,  d.mon,  d.rast,  d.rast.arrow,  d.rast. edit,  d.rastJium  d.rast. zoom  d.zoom, 
g.regiort,  r.mask,  rjlope.aspect 

AUTHORS 

Raghavan  Srinivasan  (srin@ecn.purdue.edu),  and  Chris  Rewcrts  (revverts@ecn.purdue.edu),  Agricultural 
engineering,  Purdue  University 
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NAME 

i i.Tastzoom  -  To  interactively  zoom  in  or  zoom  out  of  regions  on  a  raster  map  displayed  in  the  active 
frame  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

djast  jsoom 
d  .rust  .zoom  help 

DESCRIPTION 

d.rast.zoom  allows  the  user  to  zoom  in  or  out  of  a  region  of  interest  on  the  raster  map  layer  currently 
displayed  in  the  active  frame  of  the  graphics  monitor.  rIhe  user  zooms  in  and  out  interactively,  using  a 
mouse  to  establish  the  zoom  region.  To  zoom,  click  the  left  mouse  button  to  establish  a  comer,  then 
drag  the  mouse  to  estabilsh  the  second  (diagonal)  comer  and  hit  the  right  mouse  button  to  accept  the 
region.  "Unzoom"  will  move  back  one  step  (i.e.,  to  the  last  modified  region).  If  the  user  tries  to 
unzooin  once  again,  the  zoom  region  will  lie  set  equal  to  the  default  region  settings.  The  user  can 
zoom  or  unzoom  any  number  of  times  until  satisfied. 

NOTES 

d.rast.zoom  is  sensitive  to  the  current  mask  (see  r.mask. 

This  program  runs  only  interactively. 

This  program  remains  in  alpha  testing.  It  resides  in  the  src alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

d.frame,  d.rast,  d.rast. arrow,  d.rast.edit,  d.rast. num,  d.zoom,  gjegion,  rjnask,  and  parser 
AUTHOR 

Raghavan  Srinivasan,  Agricultural  Engineering,  Purdue  University 
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NAME 

d.rgb  -  Displays  three  user-specified  raster  map  layers  as  red,  green,  and  blue  overlays  in  the  active 
graphics  frame. 

(GRASS  Display  Program) 

SYNOPSIS 

d-rgb 
d.rgb  help 

dLrgb  [red=/iome]  [green  =/iame]  [bl ue=name]  [out  =name) 

DESCRIPTION 

RGB  stands  for  red,  green,  and  blue.  This  program  visually  overlays  up  to  three  raster  map  layers,  each 
displayed  in  either  red,  green,  or  Hue.  As  each  overlay  is  displayed  in  a  single  band,  the  intensity  at 
each  point  is  the  average  intensity  of  the  red,  green,  and  Hue  components  of  the  currently  active  color 
table.  For  example,  any  cell  that  carries  100%  intensity  for  either  red,  green,  or  blue  and  0%  intensity 
for  the  other  two  colors  will  be  represented  at  33%  intensity. 

WARNING:  Maps  that  are  using  the  "color  wave”  color  table  appear  to  be  solid  grey  when  using 
d.rgb.  The  average  intensity  of  the  colors  being  used  is  always  33%. 

This  program  sacrifices  spatial  resolution  to  provide  full  color  information.  Any  color  that  cannot  be 
fully  represented  at  a  particular  pixel  passes  the  extra  color  to  the  next  cell  right  and  down.  For 
example,  if  a  cell  is  to  show  50%  red,  but  the  closest  color  available  (without  showing  more  than  50%) 
is  40%,  the  pixie  to  the  right  and  the  pixie  below  will  be  given  an  extra  5%  red  each.  In  this  way  all 
the  color  is  provided  at  the  small  cost  of  a  slight  amount  of  blurring,  lire  result  is  very  pleasing, 
especially  on  high  resolution  screens. 

COMMAND  LINE  OPTIONS 
Parameters: 

red=name 
green=name 
blue-name 
out=name 

NOTES 

It  produces  an  image  and  (optionally)  a  raster  map  layer  with  1000  colors  (10  intensities  each  of  reel, 
green  and  blue).  The  image  and  raster  map  layers  will  not  display  properly  if  the  graphics  device  does 
not  have  at  least  1000  colors  while  the  user  is  running  in  float  colormode.  IIhls.  unless  the  display 
device  has  1000  colors,  it  is  necessary'  to  nm  tlic  GRASS  program 

d.coiormode  mode=fixed 

lie  fore  running  d.rgb.  Otherwise,  the  colors  will  be  incorrect. 

The  intensity  or  the  saturation  layers  may  lie  left  out.  This  means  that  it  is  possible  to  have  his,  hi,  or 
hs  images. 

SEE  ALSO 

hlend.sh,  d.coiormode,  d.colors,  d.colortable,  d.his,  hsv.rgb.sh,  r.mapcalc,  rgb.hsv.sh 

AUTHOR 

James  Westervelt.  U.S.  Army  (^instruction  Engineering  Research  laboratory 


Name  of  raster  map  layer  to  be  used  for  RED  component. 
Name  of  raster  map  layer  to  be  used  for  GREEN  component. 
Name  of  raster  map  lay  er  to  be  used  for  FLUE  component. 
Name  of  raster  map  layer  to  contain  results. 
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NAME 

d.rhumbline  -  Displays  the  rhumbline  joining  two  user-specified  points,  in  the  active  frame  on  the 
user’s  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.rhumbline 
djrhiunbiine  help 

dj-humbline  coor  =lonl,lall,lon2,lat2  [lcolor  =name] 

DESCRIPTION 

A  rhumbline  is  a  line  following  a  constant  angle  of  the  compass  (i.e.,  a  line  of  constant  direction). 
There  are  32  points  on  the  compass  (points  are  roughly  11  degrees  15  minutes  apart).  d.rhumbline 
displays  the  rhumbline  joining  any  two  user-specified  points  in  the  active  frame  on  the  user’s  graphics 
monitor.  The  named  coordinate  locations  must  fall  within  the  boundaries  of  the  user’s  current 
geographic  region. 

The  user  can  run  this  program  either  interactively  or  non- interactively.  If  the  user  simply  types 
djrhiunbiine  on  the  command  line  without  specify  ing  parameter  values,  the  mouse  will  be  activated 
and  the  user  will  be  asked  to  use  the  mouse  to  indicate  the  two  endpoints  of  the  rhumbline.  The 
rhumbline  is  then  drawn  in  the  default  color  (white).  The  program  also  outputs  the  coordinate  locations 
of  the  two  endpoints  on  the  user’s  terminal  and  the  number  associated  with  the  mouse  button  depressed 
by  the  user  in  a  format  useful  for  input  to  other  programs. 

Alternately,  the  user  can  specify  the  starting  and  ending  longitude/latitude  coordinates  of  the  rhumbline 
and  (optionally)  the  color  in  which  the  rhumbline  will  be  displayed;  in  this  case,  the  program  will  run 
non-interactively. 

COMMAND  LINE  OPTIONS 
Parameters: 

coor  =lonl,latl,lon2,lal2 

Starting  and  ending  coordinates  of  the  rhumblines  to  be  displayed,  given  as  longitudes  and 
latitudes. 

lcolor  =name 

Rhumbline  color. 

Options:  red,  orange,  yellow,  green,  Hue,  magenta,  indigo,  videt,  gray,  white,  black 
Default:  white 

NOTES 

This  program  works  only  with  longitude/latitude  data  bases. 

SEE  ALSO 

d.geodesic 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Constniction  Engineering  Research  Laboratory 
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NAME 

d.save  -  Creates  a  list  of  commands  for  recreating  screen  graphics. 

(GRASS  Display  Program) 

SYNOPSIS 

d^STC 
d.save  help 

d.save  [-ca]  [frame  =#iame[  /ra/ne,...]] 

DESCRIPTION 

When  GRASS  display  (d.)  commands  are  used  to  gei^rate  graphical  images  on  the  graphics  monitor, 
some  commands  are  noted  in  lists  that  the  current  graphics  driver  (see  manual  entry  for  cl.mon) 
maintains.  This  command.  d.save,  use  this  information  to  create  a  shell  script  that  can  be  used  to 
recreate  graphics  in  another  frame  at  another  time.  Ihe  shell  script  is  sent  to  standard  output  (the 
user’s  terminal).  If  you  wish  to  stive  the  shell  script  created  by  d.save,  its  output  should  be  redirected 
to  a  file;  for  example: 

d.save  >  script  .out 

The  user  can  run  the  program  non- interactively  by  specifying  flag  settings  and  parameter  values  on  the 
command  line.  If  the  user  types  d.save  without  specifying  these  program  arguments,  the  user  will  lie 
prompted  for  inputs  through  the  standard  user  interface  described  in  the  manual  entry  for  parser. 

COMMAND  LINE  OPTIONS 
Flags: 

-c  Shell  script  will  contain  only  information  for  regenerating  graphics  from  the 

active  (current)  frame.  Use  of  this  flag  overrides  the  frame  option  (below). 

-a  Save  information  needed  to  regenerate  all  the  frames  on  the  graphics  monitor. 

The  shell  script  can  be  used  to  completely  reconstnict  the  contents  of  the  graphics 
screen. 

Parameter: 

fr  ame  =name{  /iame,...] 

Name(s)  of  those  display  frame(s)  to  be  saved. 

Options:  All  available  frames 
Default:  Active  frame 

NOTES 

Display  commands  used  interactively,  and  those  that  take  their  graphic  instntetions  from  standard  input, 
will  not  be  saved  by  d.save. 

This  program  remains  under  alpha  testing.  It  resides  in  the  src.alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

d.frame,  d.mon,  d.savescreen,  g.region,  and  parser 

AUTHOR 

David  Satnik,  Central  Washington  University 
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NAMK 

d.savescreen  -  Screen  capture  utility  for  some  MASSCQMP  graphics  monitors. 

(GRASS  Display  Program) 

SYNOPSIS 

d.savescreen 

DESCRIPTION 

d.savescreen  captures  the  image  currently  displayed  on  the  graphics  monitor  in  a  form  suitable  for  later 
printing  by  p screen. 

Screen  capture  is  performed  in  two  steps.  The  displayed  image  is  first  captured  into  a  file,  and  this  file 
then  reformatted  into  the  format  required  by  p screen. 

file  capture  happens  interactively.  After  the  user  types: 

d.savescreen 

the  displayed  image  is  captured  into  a  file  and  stored  under  the  Amp  directory  on  the  user’s  machine. 
Ihe  file’s  name  is  generated  by  d.savescreen  and  has  the  form  Itmplscreen ###  (where  ###  is  a 
random  numlier).  d.savescreen  reports  the  name  of  the  Itmplscreen###  file  to  the  user  after  this  first 
step  is  completed. 

File  reformatting  goes  on  in  the  "background'  (i.e.,  the  user  can  do  other  work  at  Ins  keyboard  while 
waiting  for  die  image  to  be  reformatted).  When  the  reformat  step  is  completed,  the  user  is  notified  by 
mail  that  the  Itmplscreen### file  is  complete. 

Ihe  user  can  then  print  out  the  Itmplscreen###  file  using  p screen.  Ihe  user  must  specify  the  full 
path  of  this  file  to  p. screen. 

NOTES 

This  prognun  may  not  exist  on  your  system;  at  present,  it  only  works  on  MASSCQMP  systems. 
MASSCOMP  no  longer  supports  this  function  on  386  DVGA,  VEGA,  and  VD0600  graphics  terminals. 

This  program  requires  no  command  line  arguments. 

d.savescreen  places  its  output  in  a  file  under  the  Amp  directory,  not  under  the  user’s  mapset.  The  user 
should  specify  this  file  by  its  full  path  name  (i.e.,  Itmplscreen ###)  to  p. screen  when  printing  it  out. 

Ihe  Itmplscreen ###  files  can  be  quite  large.  Users  should  remove  these  files  after  they  have  been 
printed.  This  can  be  done  using  the  UNIX  rm  command: 

rm  Amp/screcn### 

SEE  ALSO 

UNIX  Manual  entry  for  rm 
d.display,  d.save,  pjereen,  p.select 
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NAME 

d.scale  -  Overlays  a  bar  scale  and  north  arrow  for  the  current  geographic  region  at  a  user-defined 
location  in  the  active  display  frame. 

(GRASS  Display  Program) 

SYNOPSIS 

d.scale 
d.scale  help 

d.scale  [-m]  [bctAar  =name]  [tcolor  =*uune]  [ak=x,y] 

DESCRIPTION 

d.scale  overlays  a  bar  scale  and  north  arrow  for  the  current  geographic  region  at  a  user-defined  location 
in  the  active  display  frame.  Ilie  scale  and  north  arrow  are  proportioned  to  fit  in  the  active  frame  when 
placed  along  the  frame’ s  left  edge. 

The  user  can  specify  the  location  of  the  scale  and  north  arrow  interactively  (using  a  mouse),  or  provide 
the  geographic  coordinates  at  w  hich  they  will  be  placed.  ITte  scale  and  north  arrow'  will  only  overwrite 
those  portions  of  the  graphics  display  that  lie  directly  beneath  them. 

The  user  am  also  specify  the  colors  in  which  the  scale  and  north  arrow  will  be  drawn.  By  default,  if 
unspecified  by  the  user,  a  white  scale  and  north  arrow  will  be  displayed  on  a  black  background. 

OPTIONS 

The  user  can  nur  this  program  either  non-interactivcly  or  interactively.  Ilie  program  will  lie  run  non- 
interactively  if  the  user  specifies  program  parameter  values  and  desired  flag  settings  on  tlie  command 
line,  using  the  form: 

d.scale  [-m]  [bcoior  =--name]  [tcalor  =name]  [at=jyr] 

If  at  least  one  parameter  value  is  given  on  the  command  line  and  the  -m  flag  is  not  set,  the  program 
will  be  run  non-interactively;  any  other  parameter  values  left  unspecified  on  the  command  line  w  ill  lie 
set  equal  to  their  default  values  (see  below).  Alternately,  the  user  can  simply  type  d.scale  on  the 
command  line,  without  program  arguments.  In  this  case,  the  user  will  be  prompted  for  needed 
parameter  values  and  the  flag  setting  using  the  standard  GRASS  parser  interface  described  in  the 
miuiual  entry  for  parser.  If  the  user  sets  the  -m  flag,  d. scale  will  expect  the  user  to  designate  the 
settle’s  location  interactively,  using  the  mouse. 

Flag: 

-m  Use  the  mouse  to  interactively  place  tlie  location  of  the  scale  and  north  arrow. 


Parameters: 
bcoior  name 


tcolor  =name 


at  =x,y 


Set  the  background  color  underlying  the  scale  and  north  arrow  to  name. 

Options:  red,  orange,  yellow,  green ,  blue,  indigo,  violet ,  gray,  brown, 
magenta,  white,  and  black 
Default:  black 

Set  the  foreground  color  in  which  the  text,  scale,  and  north  arrow  are  displayed  to 
name. 

Options:  Same  as  bcoior  colors. 

Default:  white 

Ihe  map  easting  (x)  and  northing  (y)  geographic  coordinates  designating  the 
location  at  which  the  upper  left  comer  of  the  scale  is  to  lie  placed.  'Ilie  user 
should  choose  geographic  coordinates  located  within  Ihe  current  geographic  region 
(see  d.where  and  g.region  for  these  coordi nates). 

Default:  0.0, 0.0 
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NOTES 

d. scale  assumes  that  layer  units  are  in  meters. 

The  scale  that  djcale  generates  is  probably  not  suitable  for  very  tiny  maps  (in  small  display  frames). 
SEE  ALSO 

d.tegend,  d.measure,  d.what.rast,  d.what.vect,  d.where,  g.region,  and  parser 
AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.sites  -  Displays  site  markers  in  the  active  display  frame  on  the  graphics  monitor. 
(GRASS  Display  Program) 

SYNOPSIS 

d.sites 
d.sites  help 

d.sites  ritefile^nome  [color  =ru2/ne]  [siz e=value]  [typ e=name] 


DESCRIPTION 

djsites  displays  a  GRASS  sitejists  map  using  site  markers  of  a  color,  size,  and  type  specified  by  the 
user.  Output  is  displayed  in  the  active  frame  on  the  graphics  monitor. 

This  program  can  be  run  non- interactively  or  interactively.  If  the  user  gives  the  name  of  a  GRASS 
sitejlists  map  and  (optionally)  specifies  other  parameter  values  on  the  command  line  the  program  will 
be  run  non- interactively;  any  parameter  values  left  unspecified  are  set  to  their  default  values  (see 
below).  Alternately,  the  user  can  type  simply  d .sites  on  the  command  line;  in  this  case,  the  program 
will  prompt  the  user  for  parameter  values  using  the  standard  GRASS  parser  interface  described  in  the 
manual  entry  for  parser. 

Parameters: 


sitefile  name 
color  =name 


size-value 


Name  of  a  GRASS  sitejists  map  in  the  user’s  current  mapset  search  path. 

Sets  the  current  color  to  name. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  black 
Default:  gray 

Size,  in  pixels,  in  which  the  site  icons  are  to  be  drawn. 

Options:  0-1000 
Default:  5 


type  =name  The  ty  pe  of  icon  to  be  displayed  at  site  locations. 

Options:  x,  diamond,  box,  + 

Default:  x 


SEE  ALSO 

d.display,  d.icons,  d.points,  d.rast,  d.sites,  d.vect,  g.region  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Anny  Construction  Engineering  Research  laboratory 
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NAME 

(Ltext  -  Daws  text  in  the  active  display  frame  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.text 
d.text  help 

dUext  [siz e=value]  [ color  =ruime]  [line=va/ue] 

DESCRIPTION 

d.text  draws  text  in  the  active  display  frame  on  the  graphics  monitor.  Text  can  be  provided  through 
standard  input  or  redirected  from  a  file  (using  the  UNIX  redirection  mechanism). 


Height  of  letters,  stated  as  a  percent  of  the  available  display  frame  height. 

Options:  0  -  100 
Default:  5 

Sets  display  text  color  to  name. 

Options:  red,  orange,  yellow,  green,  blue,  indigo,  violet,  gray,  white,  and  black 
Default:  gray 

The  screen  line  number  on  which  the  first  line  of  text  will  be  drawn. 

(Line  1  is  at  the  top  of  the  active  display  frame.) 

Options:  1  -  1000 
Default:  1 

In  addition  to  the  options  provided  on  the  command  line,  colors,  text  size,  font  type,  and  boldness,  can 
be  adjusted  with  commands  in  the  standard  input  (i.e.,  if  the  user  invokes  d.text  without  options  on  the 
command  line,  and  then  assigns  values  to  these  options  on  lines  within  the  standard  input).  In  this  case, 
the  user  also  sees  the  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

Commands: 

.C  color 

(where  color  is  one  erf  the  available  colors)  causes  text  appearing  on  subsequent  lines  to  be  drawn  in 
that  color. 

Text  size  can  be  adjusted  with  the  command: 

.S  size 

(where  size  is  a  percentage  within  the  range  0  to  100).  Note  that  a  size  of  10  would  allow  10  lines  to 
be  drawn  in  the  active  display  frame,  5  would  allow  the  drawing  of  20  lines,  and  50  would  allow  the 
drawing  of  2  lines. 

Font  type  can  be  manipulated  using  the  command: 

.F  font 

(where  font  is  one  of  the  fonts  known  by  the  GRASS  program  d.font).  Available  fonts  are  listed  in  the 
GRASS  manual  entry  for  d.font.  The  default  font  type  used  (if  unspecified  by  the  user)  is  romans. 
Run  the  GRASS  macro  show.fontsjh  to  see  what  these  fonts  look  like. 

The  user  can  also  stipulate  that  text  be  printed  in  bold  on  lines  beneath  the  command: 

.B  1 

This  command  means  bold  on  . 

Similarly,  the  command: 

.BO 

turns  bold  off  of  all  text  appearing  on  lines  beneath  it.  ( Bold  off  is  used  by  default,  if  unspecified  by 
the  user.) 


Parameters: 

siz  e=value 

color  -/lame 

line  =value 
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EXAMPLE 

The  following  command  will  print  the  short  phrase  "This  is  a  test  of  d.text"  in  the  active  display  frame 
using  die  color  yellow,  in  bold,  and  using  4/l00ths  (4%)  of  the  active  frame’s  vertical  space  per  line: 

dJext 
•C  yellow 
.S  4 
•B  1 

This  is  a  test  of  dieit 

The  user  presses  control-d  (the  "ctri"  and  "d"  keys)  to  end  input  to  d.iext. 

NOTES 

Note  that  the  GRASS  command  d.title  creates  map  titles  in  a  format  suitable  for  input  to  d.text 

d.text  needs  escape  sequences  that  can  be  used  within  lines  to  change  colors,  boldness,  and  perhaps 
size. 

SEE  ALSO 

d.font,  d.title,  show. fonts -sh,  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

d.titlc  -  Outputs  a  title  for  a  raster  map  layer  in  a  form  suitable  for  display  by  dJext. 

(GRASS  Display  Program) 

SYNOPSIS 

dJitle 
d.titlc  help 

d.title  [-f]  map  name  [color  =name]  [a»ze=va/ue] 

DESCRIPTION 

d.title  generates  to  standard  output  a  string  which  can  be  used  by  d.text  to  draw  a  title  for  the  raster 
map  layer  name  in  the  active  display  frame  on  the  graphics  monitor.  Output  created  by  dJitle  can  be 
redirected  into  a  file,  or  piped  directly  into  dJext  to  display  the  map  title  created  by  d.title.  The  map 
title  created  will  include  the  map  layer’s  name,  title,  MAPSET,  LOCATION., NAME,  geographic  region 
boundary  coordinates,  and  cell  resolution. 

The  user  can  state  program  arguments  on  the  command  line,  or  type  simply  dJitle  on  the  command 
line.  In  the  latter  case,  the  program  will  prompt  the  user  for  the  parameter  values  and  flag  setting  using 
the  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

Flag: 

-f 

Parameters: 
map  =name 
color  =name 


size  rvalue 


EXAMPLE 

For  example,  a  user  wishing  to  create  a  suitable  title  for  the  Spearfish,  SD  soils  map  layer  and  to 
display  this  title  in  the  active  display  frame  on  the  graphics  monitor  might  type  the  following: 

dJitle  map-soils  color  =red  size  —5  >  title JUe 
d.text  CtitleJile 

Alternately,  the  user  might  pipe  d.title  output  directly  into  eLtext: 

d.title  map-soils  color  =red  size  =5  |  dJext 

A  file  created  by  dJitle  can  be  displayed  with  d.text.  Information  contained  in  this  file  takes 
precedence  over  the  color  and  size  parameters  for  d.text. 

NOTES 

The  text  created  with  d.text  will  not  necessarily  fit  within  the  active  display  frame  on  the  graphics 
monitor;  the  user  should  choose  a  text  size  appropriate  to  this  frame. 

SEE  AI,SO 

d.font,  dJext  and  parser 

AUTHORS 

James  Westervelt,  U  S.  Army  Coivstmction  Engineering  Research  laboratory 
CUvid  Gerdes,  U  S.  Army  Constniction  Engineering  Research  Laboratory 


Displays  a  fancier  title. 


Name  of  an  existing  raster  map  layer  in  the  user's  mapset  search  path. 

Sets  the  current  color  to  the  name  stated. 

Qjtions:  red,  orange,  green,  blue,  indigo,  violet,  Mack,  white,  gray,  yellow, 
brown,  and  magenta 
Default:  white 

Sets  the  text  size  as  a  percentage  of  the  active  display  frame’s  height,  to  value. 
Floating  point  values  can  be  used. 

Options:  0  -  100 
Default:  15.0 
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NAME 

d.vect  ~  Displays  GRASS  vector  data  in  the  active  frame  on  the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.vect 
d.vect  help 

d.vect  map  =name  [color  =name\ 

DESCRIPTION 

d.vect  displays  the  user-named  binary  vector  file  in  the  active  display  frame  on  llie  graphics  monitor,  in 
the  user-named  color.  The  vector  file  must  already  exist  under  a  mapset  listed  in  the  user's  current 
mapset  search  path. 

This  program  can  be  nin  either  non  interactively  or  interactively.  If  the  user  gives  the  name  of  a  liinaiy 
vector  map  to  be  displayed  and  (optionally)  specifies  a  color  for  vector  display,  the  program  will  run 
non- interactively.  (If  the  user  gives  a  vector  map  name  but  no  vector  color  on  the  command  line,  the 
named  vector  map  layer  will  be  displayed  in  the  default  color  white)  Alternately,  the  user  can  simply 
type  d.vect  on  the  command  line;  in  this  case,  the  program  will  prompt  the  user  for  parameter  v  alues 
using  the  standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

Parameters: 

map  name  Vector  map  layer  to  be  displayed  in  the  active  display  frame. 

Mast  be  binary  vector  file  in  the  user’s  current  majrsct  search  path. 

color  =name  Sets  vector  display  color  to  name. 

Options:  white,  red,  orange,  yellow,  green,  blue,  indigo,  violet,  magenta, 
brown,  gray,  and  black 
Default:  white 

NOTES 

I  his  program  needs  to  be  upgraded  with  features  that  would: 

1)  Allow  different  line  colors,  weights,  and  textures  to  be  assigned  to  vectors  with  different  category 
values; 

2)  Allow  different  fill  patterns  and  colors  to  be  assigned  to  areas; 

3)  Be  linked  with  an  associated  program  identifying  these  options. 

SEE  ALSO 

d.rast,  d.sites,  tLvect.dlg,  d.whai.vect,  g.mapsets,  and  parser 

AUTHORS 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
James  Westervelt,  U.S.  Army  Construction  Engineering  Research  I  aboratory 
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NAME 

d.vect.dlg  -  Displays  a  USGS  Digital  Line  Graph  (DLG-3)  binary  vector  file  in  the  active  frame  on  the 
user’s  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.vectallg 
d.Ttctdlg  help 

d.vect^dlg  mmp=name  [  color  =namc\ 

DESCRIPTION 

d.vect.dlg  displays  a  user-specified  binary  vector  digital  line  graph  -  level  3  (DLG-3)  map  in  the  active 
frame  on  the  user’s  graphics  monitor.  The  user  can  (optionally)  specify  the  color  in  which  vectors  will 
1%  drawn.  The  map  to  be  drawn  must  exist  in  the  user’ s  current  mapset  search  path. 

This  program  can  be  run  either  non-interactively  or  interactively.  The  user  can  run  this  command  rxxv 
interactively  by  specifying  parameter  values  on  the  command  line.  Alternately,  the  user  can  simply 
type  d.vect.dlg  on  the  command  line;  in  tins  case,  the  program  will  prompt  the  user  to  enter  the  name 
of  a  DLG-3  file  and  a  vector  color  using  the  standard  interface  described  in  die  manual  entry  for 
parser. 

COMMAND  LINE  OPTIONS 
Parameters: 

map  name  Name  of  an  existing  DLG-3  map  layer  to  be  displayed. 

color  =rzume  Color  in  which  vectors  will  be  drawn. 

Options:  white,  red,  orange,  yellcw,  green,  blue,  indigo,  violet,  gray,  black 
Default:  gray 

NOTES 

This  program  will  probably  be  phased  out  and  is  included  only  to  provide  some  backward  compatibility 
with  previous  GRASS  versions  (eg.,  version  2.0). 

The  command  gJist  type  vect  only  lists  binary  vector  files  in  GRASS  format  (i.e.,  dig  files);  it  does 
not  list  binary  vector  DLG-3  files  (bdlg  files)  stored  under  the  user’s  mapset.  However,  die  user  can 
list  the  DIG-3  files  accessible  to  him  by  running  d.vect.dlg  interactively. 

SEE  ALSO 

d.rast,  d.sites,  d.vect,  g.mapsets,  v.import,  v.in.dlg,  v. out. dig,  and  parser 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 


GRASS  4.0  (Summer  1WI) 


IJ.S  Army  (  ERL 


77 


d.whatxast 


(TRASS  Reference  Manual 


d.\shat.rast 


NAME 

d.what.rast  -  Allows  the  user  to  interactively  query  the  category  contents  of  multiple  raster  map  layers 
at  user-specified  locations  within  the  current  geographic  region. 

(GRASS  Display  Program) 

SYNOPSIS 

d.whatxast 
d.what  j-ast  help 

d.whatjrast  [-It]  [ map  =name[/iame ,...]]  [fs  =name] 

DESCRIPTION 

d.what.rast  outputs  the  category  values  and  labels  associated  with  cell(s)  at  user-specified  location(s) 
on  user-named  raster  map  layers). 

The  program  will  query  the  contents  of  raster  map  layers)  named  by  the  user  on  the  command  line. 
These  map  layers  must  exist  in  the  user’s  current  map6et  search  path.  If  the  user  docs  not  name  any 
raster  map  layers  on  the  command  line,  d.what.rast  will  query  the  category  contents  of  whatever  raster 
map  layer  is  already  displayed  in  the  active  frame  on  the  graphics  monitor. 

The  program  activates  the  mouse,  and  expects  the  user  to  indicate  the  cell  location(s)  to  be  queried  by 
depressing  a  mouse  button  over  desired  location(s)  within  the  current  geographic  region  in  the  active- 
display  frame  on  the  graphic  monitor. 

Flags: 

-1  Identify  and  query  just  one  point  location.  Only  one  mouse  click  is  executed. 

This  option  is  provided  for  shell  scripts  and  programs  that  want  to  obtam  only  one 
point  from  the  user. 

-t  Provide  only  terse  output.  This  option  is  provided  to  simplify  the  parsing  of 

output  by  other  programs. 

Parameters: 

map=name  Name  of  existing  raster  map  layer(s).  Limit:  15  maps 

Default:  CXiery  map  currently  displayed  in  the  active  graphics  frame. 

fs  =name  Output  Held  separator  to  be  used  (in  terse  mode  only  ). 

Default:  : 

d.what.rast  output  consists  of  the  geographic  coordinates  of  the  location  pointed  to,  and,  for  each  map 
layer,  the  map  layer  name,  the  category  value,  and  category  label  in  the  named  raster  map  lay  ers  at  this 
location. 

EXAMPLE 

It  is  helpful,  Ixit  not  necessary,  to  first  display  a  map  to  Ire  used  for  reference  in  (Ik-  active  display 
frame  before  miming  d.what.rast.  For  example,  the  user  might  type  the  following  series  of  commands 
and  receive  the  output  below. 

drast  map -  soils 

To  first  ilisplav  the  soils  map  in  the  active  frame. 

d.whatxast  map  soil  s,aspect 

User  then  moves  the  mouse  to  desired  location  on  the  displayed  soils  map  layer. 
;uid  presses  the  left  mouse  button  to  query  the  category  contents  of  the  soils  and 
aspect  maps  at  this  geographic  hxatiou.  Ilie  pngram  then  ouqxits  the  IxTow 
information  to  the  user’s  terminal. 
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617112(E)  3732014(N) 

soils  in  PERMANENT  (44)Nunn  clay  loam,  NdC 
aspect  in  PERMANENT  (20)15  degrees  north  of  west 

I  he  first  line  of  output  gives  the  easting  (E)  and  northing  (N)  coordinates  of  the  geographic  location  at 
which  the  user  clicked  the  mouse.  The  subsequent  two  lines  give  the  map  name  and  mapset,  map 
category  value  (within  parentheses),  and  map  category  label  corresponding  to  this  user-selected  map 
location,  for  each  of  the  maps  queried  by  the  user. 

The  query  may  be  repeated  as  often  as  desired  using  the  left  mouse  button.  The  right  button  on  the 
mouse  is  used  to  quit  the  d.what.rast  session. 

Users  can  set  the  -t  flag  to  obtain  a  terse  output  from  d.what.rast.  This  is  useful  when  the  user  wishes 
output  to  be  parsed  another  program  (like  awk).  If  the  -t  flag  is  set,  users  can  also  select  the  field 
separator  used  (with  the  is=name  option),  or  elect  to  use  the  default  :  field  separator.  In  this  case,  the 
command 

d.whatxast  -t  map=so«  I  suspect 

produces  output  in  the  form  shown  belcw.  The  first  line  of  output  gives  the 
easting,  northing,  and  the  mouse  button  return  value  (see  NOTES,  below).  Each 
subsequent  line  gives  the  map  name  and  its  mapset,  the  category  value,  and 
category  label  of  the  point  specified  on  the  user-named  raster  map  layers.  The 
default  output  field  separator,  a  colon,  is  used  since  none  was  specified  on  the 
command  line. 


617112:3732014:1 

soils@PERMANENT.44  :Nunn  clay  loam,  NdC 
aspect@PEJRMANENT :20 : 15  degrees  north  of  west 

Users  can  also  use  this  program  inside  of  shell  scripts  that  require  as  input  a  map  category  value  and  a 
mouse  button  depressed.  Users  can  choose  an  option  to  run  dLwhat.rast  only  once,  and  return  only  the 
map  category  value  found  and  the  number  of  the  mouse  button  depressed. 

NOTES 

Mouse  button  return  values  are  as  follows:  0  indicates  no  button  was  pressed,  1  indicates  that  the  left 
mouse  button  was  pressed,  2  indicates  the  middle  button  was  pressed,  and  3  indicates  that  the  right 
mouse  button  was  pressed. 

d.what.rast  will  always  print  its  output  to  the  terminal  screen  d.whal.rast  output  can  be  redirected 
into  a  file;  however,  if  it  is,  the  output  will  go  both  to  the  screen  and  to  the  file.  For  example: 

d.whatxast  map —soil  suspect  >  what  .out 

will  both  send  d.what.rast  output  to  the  screen  and  capture  its  output  in  the  file  named  what. out. 

The  maximum  number  of  raster  map  layers  that  can  be  queried  at  one  time  is  15. 

d.what.vect  allows  the  user  to  interactively  query  the  category  contents  of  multiple  vector  map  layers 
at  user- specified  locations. 

SEE  ALSO 

d.rast,  d.what.vect,  d.where,  g.region,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Constmction  Engineering  Research  Laboratory 
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NAME 

d.what.vect  -  Allows  the  user  to  interactively  query  the  category'  contaits  of  a  (binary)  vector  map 
layer  at  user-selected  locations  within  the  current  geographic  region. 

(GRASS  Display  Program) 

SYNOPSIS 

d.what.vect 
d.what.vect  help 
d.what.vect  [-1]  map  -name 

DESCRIPTION 

d.what.vect  outputs  the  category  value(s)  associated  with  user- specified  location(s)  in  a  user-specified 
vector  map  layer.  This  program  currently  returns  only  category  values  for  line  types  in  the  user- 
specified  vector  file. 

The  program  will  query  the  contents  of  the  vector  map  layer  named  by  the  user  on  the  command  line. 
This  map  layer  must  exist  in  the  user’s  current  mapset  search  path. 

The  program  activates  the  mouse,  and  expects  the  user  to  indicate  the  locations)  to  be  queried  by 
depressing  a  mouse  button  over  desired  locations)  within  the  current  geographic  region  in  the  active 
display  frame  on  the  graphic  monitor. 

Flag: 

-1  Identify  and  query  just  one  point  location.  Only  one  mouse  click  is  executed. 

This  option  is  provided  for  shell  scripts  and  programs  that  want  to  obtain  only  one 
point  from  the  user. 

Parameter: 

map  name  Name  of  an  existing  binary'  vector  map  in  the  user’s  mapset  search  path. 

EXAMPLE 

A  sample  d.what.vect  session  is  given  below.  Although  it  is  not  necessary  that  the  user  first  display  a 
vector  map  to  be  queried  in  the  active  display  frame,  it  is  helpful  to  have  a  map  displayed  tliere  for 
reference. 

d.vect  map=road&24000 

Displays  the  1:24,000  scale  roads  vector  map  layer  on  the  graphics  monitor. 


d.what.vect  map  roads.24000 

After  typing  this,  the  user  moves  the  mouse  to  a  desired  location  on  (he  displayed 
roads  map  layer,  and  presses  the  left  mouse  button  to  query'  the  category  value  of 
the  roads  vector  map  at  this  location.  The  program  then  outputs  the  category 
value  of  a  line  type  corresponding  to  this  user-selected  map  location,  for  the 
vector  map  queried  by  tlx:  user. 

Ihe  query  may  lx*  repeated  as  often  as  desired  using  the  left  mouse  button.  ' Un¬ 
rig  ht  button  on  the  mouse  is  used  to  quit  the  d.what.vect  session. 

Users  can  also  use  this  program  inside  of  shell  scripts  that  require  as  input  a  map  category  value  ami  a 
nxxise  lx  it  ton  depressed.  Users  can  set  the  1  (lag  to  mu  d.what.vect  only  once,  and  return  <>nl\  the 
map  category  value  found  and  the  nuiriber  ol  the  mouse  Ixitton  depressed.  (Mouse  Ixitlon  return  values 
are  as  follows:  0  indicates  no  Ixitton  was  pressed.  1  iixficatcs  that  the  left  nxxise  Ixitton  was  pressed.  2 
indicates  the  middle  Ixitton  was  pressed,  and  3  indicates  that  the  right  nxxise  button  was  pressed.) 


■SO 
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NOTES 

Currently,  (Lwhat.vect  only  outputs  category  values  for  lines.  It  does  not  output  category  labels  for 
lines,  nor  output  category  values  or  category  labels  for  areas  in  a  vector  file. 

d.what.vect  will  always  print  its  output  to  the  user’s  terminal  screen.  (Lwhat.vect  output  can  be 
redirected  into  a  file;  however,  if  it  is,  the  output  will  go  both  to  the  screen  and  to  the  file.  For 
example: 

d.whkt.Tcd  map  roads  >  what. out 

will  both  send  d.what.vect  output  to  the  screen  and  capture  its  output  in  the  file  named  what. out. 

d.what.rast  can  be  used  to  interactively  query  the  map  category  contents  of  multiple  raster  map  layers 
at  user-selected  locations. 

SEE  ALSO 

d.rast,  d.vect,  d.what.rast,  g.region,  and  parser 
AUTHORS 

Original  Program:  James  Uinthom,  Central  Washington  University 
Upgrades:  Dennis  Finch,  National  Park  Service 
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NAME 

d.where  -  Identifies  the  geographic  coordinates  associated  with  point  locations  in  the  active  frame  on 
the  graphics  monitor. 

(GRASS  Display  Program) 

SYNOPSIS 

d.where 
d.where  help 

d.where  [-1]  [spheroid  =name] 

DESCRIPTION 

d.where  is  an  interactive  program  that  allows  the  user,  using  the  pointing  device  (mouse),  to  identify 
the  geographic  coordinates  associated  with  point  locatioas  within  the  current  geographic  region  in  the 
active  display  frame  on  the  graphics  monitor. 

If  the  user  mns  d.where  without  specifying  the  name  of  a  spheroid  on  the  command  line,  each  mouse 
click  will  output  the  UIM  easting  ana  northing  of  the  point  currently  located  beneath  the  mouse 
pointer.  A  mouse-button  menu  is  presented  so  the  user  knows  which  mouse  buttons  to  use.  'Hie  output 
is  always  printed  to  the  terminal  screen;  if  the  output  is  redirected  into  a  file  it  will  be  written  to  the 
file  as  well. 

Flag: 

-1  Only  one  mouse  click  is  executed. 

This  option  is  provided  for  shell  scripts  and  programs  which  want  to  obtain  only 
one  point  from  the  user.  The  output  is  only  written  to  stdout,  unless  redirected 
into  a  file.  The  geographic  location  and  mouse  button  pressed  are  output. 

Parameter: 

spheroid  name  Name  of  a  spheroid  (for  kitiiiide^ongi tude  coordinate  conversion). 

Options:  australian,  bessel,  clark66,  clark80,  everest,  international,  vvgs72,  wgs84 

NOTES 

This  program  uses  the  current  geographic  region  setting  and  active  frame.  It  is  not  necessary,  although 
useful,  to  have  displayed  a  map  in  the  current  frame  before  n inning  d.where. 

SEE  ALSO 

d. what. rust,  d.what.vect,  g.region 
AUTHORS 

James  Westervelt,  U.S.  Army  Constniction  Fngincering  Research  laboratory' 

Michael  Shapiro,  U.S.  Army  Construction  engineering  Research  laboratory 
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NAME 

d.zoom  -  Allows  the  user  to  change  the  current  geographic  region  settings  interactively,  with  a  mouse. 
(GRASS  Display  Program) 

SYNOPSIS 

d.zoom 
d.zoom  help 

djcoom  [-q]  [action  =name] 

DESCRIPTION 

d.zoom  allows  the  user  to  interactively  adjust  the  settings  of  the  current  geographic  region  using  a 
pointing  device  such  as  a  mouse,  like  g.region,  dzzoom  re-deftnes  the  settings  of  the  geographic 
region.  However,  d.zoom  allows  the  user  to  change  the  current  region  settings  interactively,  by  either 
outlining  the  new  region  perimeter  with  a  mouse  or  "rotating"  latituderfongitude  data  into  the  current 
region.  The  user  should  run  (Lerase  after  dzzoom  is  run  for  the  new  region  settings  to  affect  the 
graphics  display. 

Flag: 

-q  Run  quietly,  suppressing  output  of  some  program  messages  to  standard  output. 

Parameter: 

action  =name  Allows  the  user  to  change  the  geographic  region  settings  by  "rotating"  the  globe 
to  move  a  different  portion  of  the  globe  into  the  stationery  booted  region  outline 
(making  this  new  portion  of  the  globe  the  new  current  region),  rather  than  by 
moving  the  boxed  region  outline.  This  option  can  only  be  used  with 
latitude/longitude  data  bases  (although  dzzoom  will  not  complain  if  the  user 
attempts  to  set  this  parameter  while  running  on  a  non-latitude/longitude  data 
base). 

Options:  zoom,  rotate 

After  the  user  types  the  command  djoam  and  (optionally)  sets  the  -q  flag  and  type  erf  zoom  to  be 
performed,  a  mouse-button  menu  will  appear,  directing  the  user  to:  establish  the  comers  of  the  new 
geographic  region,  check  its  coordinates,  and  confirm  any  changes  made.  When  the  user  accepts  new 
geographic  boundaries,  d.zoam  asks, 

Accept  new  region?  Y  /  N> 

If  the  user  clicks  the  mouse  over  the  "Y  (yes),  the  mouse-drawn  geographic  region  is  saved  as  the 
user’s  current  geographic  region.  The  user  is  warned  that  d.erase  should  be  run  after  dLzoom  to  make 
new  current  region  settings  affect  the  graphics  display. 

If  the  user  clicks  the  mouse  over  the  ”N"  (no),  the  first  mouse-drawn  geographic  region  is  not  saved; 
instead,  d.zoom  asks  whether  or  not  the  user  wishes  to 

Try  Again?  Y /  N  > 

The  user  can  then  opt  to  draw  a  new  region  with  the  mouse  ("Y"),  or  opt  to  exit  d.zoom  ("N”)  and 
leave  current  region  settings  unchanged. 

To  zoom- out  to  a  larger  area  than  was  windowed-in  on  with  d.zoom  (i.e.,  to  enlarge  the  current 
geographic  region),  the  user  may  run  g.region.  The  user  may  also  alter  the  current  geographic  region 
by  running  the  "region"  option  of  the  d.display  program. 

NOTES 

Although  it  is  not  necessary  that  the  user  display  a  map  in  the  active  display  frame  before  nmning 
d.zoom,  it  is  helpful  to  do  this  for  reference. 

Currently,  the  ntbter- banded  boundaries  of  the  zoom  region  drawn  by  the  user  are  not  clearly  visible  on 
the  graphics  monitor.  However,  whether  or  not  these  boundaries  are  clearly  visible  when  drawn,  the 
drawn  region  is  still  correctly  zoomed-in  on. 
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SEE  ALSO 

d.display,  d.erase,  d.rast,  g. region 

AUTHOR 

Michael  Shapiro,  U.S.  Ami)  Construction  Engineering  Research  Laboratory 
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NAME 

exit  -  Exits  the  user  from  the  current  GRASS  session. 

SYNOPSIS 

exit 

DESCRIPTION 

The  exit  command  ends  the  user’s  current  GRASS  session  and  returns  the  user  to  the  directory  in 
which  he/she  was  working  prior  to  entering  GRASS.  When  the  user  exits  GRASS,  he/she  is  asked 
whether  he/she  wishes  to  save  the  files  and  data  stored  under  his  current  mapset,  and  (if  maps  are 
present)  whether  the  user  wishes  to  selectively  remove  map  layers,  before  exiting  the  system.  By 
default,  if  the  user  presses  RETURN  without  responding  to  these  questions,  all  maps  in  the  user’s 
current  mapset  are  saved.  However,  because  such  maps  car  consume  much  storage  space  on  the 
computer,  the  user  should  remove  any  unneeded  files  before  exiting.  (The  user  can  also  remove  data 
before  attempting  to  exit  GRASS  using  the  g. remove  command.) 

Before  typing  exit,  the  polite  user  should  remember  to  release  the  graphics  display  monitor  (using  the 
command  djnon  -r)  for  use  by  other  GRASS  users.  Otherwise,  the  display  device  may  be  locked  for 
use  by  the  user,  even  though  the  user  has  exited  GRASS,  until  another  user  runs  cLmon  and  unlocks 
this  monitor  for  others’  use. 

Each  time  the  user  re-enters  GRASS,  the  variables  described  in  g.gisenv  are  re-set.  If  the  user  wishes 
to  change  the  mapset,  location,  or  data  base  on  which  he/she  is  working  (ie.,  those  affected  by  any 
GRASS  programs  running  during  the  user’s  current  GRASS  session),  the  user  must  exit  GRASS  and 
then  re-enter  GRASS  and  specify  a  different  mapset,  location,  and/or  data  base  location  on  the  GRASS 
start-up  page.  When  the  user  re-enters  GRASS,  these  variable  settings  (the  current  mapset,  location, 
and  data  base)  are  set  by  default  to  those  used  in  the  user’s  previous  GRASS  session,  unless  changed  by 
the  user. 

NOTES 

This  program  requires  no  command  line  arguments;  the  user  simply  types  exit  on  the  command  line  to 
exit  GRASS. 

SEE  ALSO 

d.mon,  g.gisenv,  g. remove 
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NAME 

g. access  -  Controls  user  access  to  the  current  GRASS  mapsct. 

(GRASS  File  Management  Program) 

SYNOPSIS 

ga»ccess 

DESCRIPTION 

Ihis  program  allows  the  user  to  control  access  to  the  current  mapsct.  Normally,  any  user  can  read  data 
from  any  GRASS  mapset.  But  sometimes  it  is  desirable  to  proliibit  access  to  certain  sensitive  data. 
The  g.access  command  allows  a  user  to  restrict  read  and  execute  access  to  the  current  mapset  (see 
UNIX  chmod  command),  g.access  will  not  modify  write  access  to  the  current  mapset. 

Ihe  user  may,  for  example,  allow  only  users  in  the  same  UNIX  grixip  to  read  data  files  in  the  mapset, 
or  restrict  the  mapset  to  personal  use  only. 

After  ty  ping 

g-acce.vs 

the  user  will  be  presented  with  a  screen  page  which  reflects  the  current  mapset  permissions.  Ihe  user 
can  then  change  them.  The  screen  page  looks  like: 


LOCATION:  spearfish  MARSEL  demo 

This  program  allow  s  you  to  control  access  to  your  mapset  by  other  users. 

Access  may  be  granted/removed  for  everyone,  or  for  everyone  in  your  group. 

Mark  an  ’x’  to  allow  access;  erase  the  field  to  restrict  access. 

GROUP: 

OTHER:  x 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
_ (OR  CtrlOTO  CANCEL) _ 


If  you  remove  the  x  (using  the  space  bar),  access  will  be  denied  to  that  class  of  user  (grtxip  or  oilier). 
If  you  type  an  x,  access  will  be  granted  to  that  class  of  user. 

NOTES 

There  is  no  non  interactive  version  of  g. access. 

Under  GRASS  version  4.0,  access  to  the  mapset  PERMANENT  must  be  open  to  all  users.  Ihis  is 
because  GRASS  looks  for  the  user’s  default  geographic  region  definition  settings  and  the  fixation  title 
in  files  that  are  stored  under  the  PERMANENT  mapset  directory.  Hie  g. access  command,  tlierefore, 
will  not  allow  you  to  restrict  access  to  the  PERMANENT  mapset. 

The  g.mapsets  command  isn’t  smart  enough  to  tell  if  access  to  a  specified  mapset  is  restricted,  and  the 
user  is  therefore  allowed  to  include  the  names  of  restricted  mapsets  in  his  search  jxith.  However,  the 
data  in  a  restricted  mapset  is  still  protected;  any  attempts  to  look  for  or  use  data  in  a  restricted  mapset 
will  fail.  The  user  will  simply  not  see  any  data  listed  for  a  restricted  mapsct. 

SEE  ALSO 

UNIX  manual  entries  for  chmod  .and  group 
g.mapsets 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

g.ask  -  Prompts  the  user  for  the  names  of  GRASS  data  base  files. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g-ask  help 

g-ask  type=name  [prompt ="string“]  element  =name  [desc="jfrmg”J  unixfile  =/!a/ne 
DESCRIPTION 

g.ask  is  designed  for  shell  scripts  that  need  to  prompt  the  user  for  the  name  of  a  data  base  file  in  the 
user’s  current  GRASS  location.  After  g.ask  is  invoked  with  needed  parameters,  it  will  query  the  user 
for  a  file  name  of  the  specified  type  and  element.  After  the  user  responds  to  this  query,  the  program 
will  write  four  lines  to  the  UNIX  output  file  specified  by  unixfile. 

Parameters: 


typ e=name 


prompt  ="st  ring” 


element  name 


desc  ="  string" 


unixfile  =name 


The  type  of  query.  Options  for  name  are  old,  new,  any,  and  mapset;  their 
functions  are  given  below.  "New",  "any",  and  "mapset”  only  look  in  the  user’s 
current  mapset. 

old  For  existing  data  files  anywhere  in  die  user’ s  mapset  search  path. 

new  Used  to  create  a  new  file  in  the  current  mapset,  which  must  not  already 

exist  there  (if  a  file  with  this  name  exists  there,  it  will  not  be 
overwritten). 

any  Creates  a  file  in  the  current  mapset,  which  may  or  may  not  already  exist 
there.  If  a  file  with  this  name  exists  in  the  current  mapset,  it  will  be 
overwritten;  if  not,  a  new  file  with  this  name  will  be  created. 

mapset  For  files  that  must  exist  in  the  current  mapset.  The  shell  write  wants  the 
name  of  a  file  that  exists  in  the  user’s  current  mapset.  This  type  would 
be  used  instead  erf  "old"  if  the  file  is  to  be  modified. 

The  prompt  to  be  displayed  to  the  user.  If  more  than  one  word,  the  promp' 
should  be  enclosed  within  double  quotes  (”"). 

Ihe  name  of  the  GRASS  data  base  element  (i.e.,  directory  under  a  GRASS 
mapset)  whose  files  are  to  be  queried. 

A  short  description  of  the  data  base  element  which  is  meaningful  to  the  user.  If 
description  contains  more  than  one  word,  it  should  be  enclosed  within  double 
quotes  (""). 

The  name  of  a  UNIX  file  to  store  the  user’s  response.  See  next  section  for  what 
is  written  to  this  file  and  how  it  can  be  used  by  shell  scripts. 


OUTPUT 

Upon  receiving  the  user’s  response  to  its  request  for  a  file  name,  g.ask  writes  four  lines  to  the  specified 
unixfile,  this  outjxit  file  is  placed  in  the  user’s  current  working  directory,  unless  otherwise  specified, 
and  contains  the  following  lines: 


name  some  _name' 
mapset  'some_mapset' 
full  name  '  some_fullname’ 
file  some  full  path' 


Ihe  output  is  /bin/sh  commands  to  set  the  variable  name  to  the  file  name  specified  ly  the  user  (of  the 
element  and  type  requested  try  g.ask),  mapset  to  the  GRASS  mapset  in  which  this  file  rcsitles  (,>r  will 
lie  creMcd),  full  name  is  the  name  with  the  mapset  embedded  in  it,  and  file  to  the  full  UNIX  path  name 
identifying  this  file.  Ihese  variables  may  lie  set  in  the  /liin/sh  as  follows; 

.  unixfile 
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The  .  is  a  shell  command  which  means  read  the  unixfile  and  execute  the  commands  found  there.  It  is 
NOT  part  of  the  unixfile  name  and  MUST  be  followed  by  a  space. 

NOTES 

The  user  may  choose  to  simply  hit  the  return  key  and  not  enter  a  file  name.  If  this  happens  the 
variables  will  be  set  as  follows: 

name= 
mapset= 
full  name = 
file= 


The  following  is  a  way  to  test  for  this  case: 
if  [  !  "Sfile"  ] 
then 

exit 

fi 


SEE  ALSO 

d.ask,  g.JUename,  g.findfile,  g.gisenv 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

gcopy  -  Copies  available  data  files  in  the  user’s  current  mapset  search  path  and  location  to  the 
appropriate  element  directories  under  die  user’ s  current  mapset. 

(GRASS  File  Management  Program) 

SYNOPSIS 

gcopy 
g  copy  help 

g.copy  [rast  =from,to]  [vect  =from,to]  [icon  =from,to\  [labds=/rom,to]  [  sites  =/rom,fo] 

[region  =from,to]  [granp=from,to] 

DESCRIPTION 

A  user  may  access  data  stored  under  the  other  mapsets  listed  in  his/her  mapset  search  path.  However, 
the  user  may  only  modify  data  stored  under  his/her  own  current  mapset.  g.copy  allows  the  user  to 
copy  existing  data  files  from  other  mapsets  to  the  user’s  current  mapset  (SMAPSET).  The  files  to  be 
copied  must  exist  in  the  user’s  current  mapset  search  path  and  location;  output  is  sent  to  the  relevant 
data  element  directory(ies)  under  the  user’s  current  mapset. 

The  user  specifies  the  type(s)  of  data  files  he/she  wishes  to  copy  (raster,  vector,  etc.),  the  name  of  the 
existing  file  to  be  copied  (i.e.,  the  from  file  name),  and  the  name  of  the  new  file  copy  to  be  placed  in 
the  user’s  current  mapset  (the  to  file  name).  This  information  can  be  given  either  (non- interactively )  on 
the  command  line,  or  entered  in  response  to  program  prompts  given  via  the  standard  parser  interface 
described  in  the  manual  entry  for  parser. 

Information  can  be  entered  on  the  command  line  in  the  following  format: 

g.copy  [ra st=from,to]  [ vect  =from,to\  [icon  =from,to\  [labels  =from,to]  [M**=from,to] 
[region  =frcm,to]  [graap=jrom,to] 

For  example,  if  the  user  wished  to  copy  the  existing  raster  file  soils  to  a  file  called  soils. ph  and  to 
copy  an  existing  vector  file  roads  to  a  file  called  rds.oid,  the  user  could  type: 

gxopy  rast=soils^oils.ph  vect=ronds^rds.old 

Data  files  can  also  be  specified  by  their  mapsets.  For  example,  the  below  command  copies  the  raster 
file  named  soils  from  the  mapset  wilson  to  a  new  file  called  soils  to  be  placed  under  the  user’s  current 
mapset: 

g-copy  rast=’soil9@wilson’,MiIs 

If  no  mapset  name  is  specified,  g  copy  searches  for  the  named  from  map  in  each  of  the  mapset 
directories  listed  in  the  user’s  current  mapset  search  path  in  the  order  in  which  mapsets  are  listed  there 
(see  g mapsets). 

If  the  user  does  not  enter  parameter  values  but  instead  types  only  %xopy  on  the  command  fine  the 
program  will  prompt  the  user  for  a  data  type,  the  name  of  a  file  of  this  data  type  to  copy,  and  the  name 
of  a  new  file  to  hold  the  copy.  After  both  file  names  have  been  entered,  the  copy  is  created  and  the 
user  is  again  prompted  for  a  data  element  to  be  copied,  until  the  user  hits  RETURN.  When  prompted 
for  file  names,  the  user  may  enter  ’list’  to  see  a  fist  of  existing  files,  or  hit  RETURN  to  end  the  file 
listing. 
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Parameters: 

rast  =from,to 

where  from  is  an  existing  raster  map  layer  to  be  copied,  and  to  is  the  name 
given  to  the  copy. 

vect=from,to 

where  from  is  an  existing  binary  vector  map  layer  to  be  copied,  and  to  is  the 
name  given  to  the  copy. 

icon  =from,to 

where  from  is  an  existing  paint  icon  file  to  be  copied,  and  to  is  the  name  given 
to  the  copy. 

1  abd  s  =from,  to 

where  from  is  an  existing  file  to  be  copied,  and  to  is  the  name 

given  to  the  copy . 

sit  e»=from,to 

where  from  is  an  existing  site_lists  file  to  be  copied,  and  to  is  the  name  given 
to  the  copy. 

region  —from,  to 

where  from  is  an  existing  region  definition  ( windows )  file  to  be  copied,  and  to 
is  the  name  given  to  the  copy. 

group  =from,to 

where  from  is  an  existing  imagery  group  file  to  be  copied,  and  to  is  the  name 
given  to  the  copy. 

NOTE 

If  a  file  has  support  files  (eg.,  as  do  raster  data  files),  these  support  files  will  also  be  copied. 

SEE  ALSO 

g.access,  g.list,  gjnapsets,  g.remove,  g. rename,  and  parser 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

g. filename  -  Prints  GRASS  data  base  file  names. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g.  filename 
gjfilename  help 

g .filename  element  name  mapset  name  SI t=name 
DESCRIPTION 

g. file  name  is  designed  for  Bourne  shell  scripts  that  need  to  know  the  full  UNIX  file  name  for  raster 
map  layers,  vector  files,  site  list  files,  geographic  region  definition  (windows)  files,  imagery  group  files, 
etc.,  in  the  GRASS  data  base.  If  the  user  runs  g.filename  without  command  line  arguments  (i.e., 
simply  types  g -filename),  this  program  will  prompt  the  user  for  input  using  the  standard  parser 
interface  described  in  the  manual  entry  for  parser. 

Parameters: 

element  name  The  name  of  a  GRASS  data  base  element  (i.e.,  directory  within  the  GRASS 
mapset  location). 

mapset  name  The  name  of  a  GRASS  data  base  mapset.  As  a  convenience,  a  single  dot  (.)  can 
be  used  to  designate  the  current  mapset. 

file  ^narne  The  name  of  a  GRASS  data  base  file. 

OUTPUT 

g.filename  writes  one  line  to  standard  output: 
til  e  -fullfile  pathname  ’ 

The  output  is  a  /bin/sh  command  to  set  the  variable  specified  by  the  file  name  to  the  full  UNIX  path 
name  for  the  data  base  file.  This  variable  may  be  set  in  the  /bin/sh  as  follows: 

eval  g. filename  element  name  mapset  =*UJ/ne  file  —name 

NOTES 

This  routine  generates  the  filenanre,  but  does  not  care  if  the  file  (or  mapset  or  element)  exists  or  not. 
This  feature  allows  shell  scripts  to  create  new  data  base  files  as  well  as  use  existing  ones. 

If  the  mapset  is  the  current  mapset,  g.filename  automatically  creates  the  element  specified  if  it  doesn’t 
already  exist.  This  makes  it  easy  to  add  new  files  to  the  data  base  without  having  to  worry'  about  the 
existence  of  the  required  data  base  directories.  (This  program  will  not  create  a  new  mapset,  however,  if 
that  specified  does  not  currently  exist.) 

The  program  exits  with  a  0  if  everything  is  ok;  it  exits  witn  a  non-zero  value  if  there  is  an  error,  in 
which  case  file  -  ‘full  file  pathname '  is  not  output 

SEE  ALSO 

g.ask,  g.findfile,  g.gisenv,  and  parser 

AUTHOR 

Michael  Shapiro,  US.  Army  (onstniction  l;ngi  nee  ring  Research  laboratory 


CiRASS  4.0  (Summer  1991) 


U  S.  Annv  (TRI. 


91 


gJindfile 


GRASS  Reference  Manual 


idfile 


NAME 

g.findfUe  -  Searches  for  GRASS  data  base  files  and  sets  variables  for  the  shell. 

(GRASS  File  Management  Program) 

SYNOPSIS 

gJindfile  help 

giindfile  element  name  }  mapset  name  ]  fil t=name 
DESCRIPTION 

g.findfUe  is  designed  for  Bourne  shell  scripts  that  need  to  search  for  raster  map  layer  files,  vector  files, 
site  list  files,  geographic  region  definition  (windows)  files,  and  imagery  group  files  in  the  GRASS  data 
base.  If  the  user  runs  g.findfUe  without  command  line  arguments,  he  will  be  prompted  for  the  names  of 
a  GRASS  element,  file,  and  mapset,  through  the  standard  parser  interface  (see  manual  entry  for  parser). 

Parameters: 
element  -name 
mapset  name 


Ble=name 
OUTPUT 

g.findfUe  writes  three  lines  to  standard  output: 

name =fUe  _name  ’ 
mapset  =  mapset  jname’ 
file=’  unix_fUename' 
fuUmmc =’  grass^fullname’ 

The  output  is  /bin/sh  commands  to  set  the  variable  name  to  the  GRASS  data  base  file  name,  mapset  to 
the  mapset  in  which  the  file  resides,  and  file  to  the  full  UNIX  path  name  for  the  named  file.  These 
variables  may  be  set  in  the  /bin/sh  as  follows: 

eval  g. find  file  element  name  mapset  name  name  =  name 

NOTES 

If  the  specified  file  does  not  exist,  the  variables  will  be  set  as  follows: 
name= 
mapset  = 
full  name = 
file= 

The  following  is  a  way  to  test  for  this  case: 

if  [  !  "Sfile"  ] 
then 

exit 

fi 

SEE  ALSO 

g.ask,  g.filename,  g.gisenv,  gjnapsets,  and  parser 

AUTHOR 

Michael  Shapiro.  US.  Anny  G>nstniction  brig  i  nee  ring  Research  laboratory 


The  data  base  element  (i.e.,  directory  within  a  GRASS  mapset)  to  be  searched. 

The  mapset  in  which  to  search  for  the  specified  file  name.  If  not  specified,  all 
mapsets  in  the  user’s  GRASS  search  path  are  searched.  Oherwise,  the  specified 
mapset  is  searched.  As  a  convenience,  if  specified  as  a  single  dot  (.)  only  the 
current  mapset  is  searched. 

The  name  erf  a  GRASS  data  file  (of  the  stated  element  type)  for  which  to  search. 
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NAME 

g.gisenv  -  Outputs  the  user’s  current  GRASS  variable  settings. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g^isenv 

g.gisenv  [variable __name] 

DESCRIPTION 

When  a  user  runs  GRASS,  certain  variables  are  set  specifying  the  GRASS  data  base,  location,  inapset, 
peripheral  device  drivers,  etc.,  being  used  in  the  current  GRASS  session.  These  variable  name  settings 
are  recognized  as  long  as  the  user  is  running  a  GRASS  session. 

No  prompts  are  given  to  the  user  when  running  g.gisenv.  If  run  without  arguments,  g.gisenv  lists  all 
of  the  user’s  current  GRASS  variable  settings.  Results  are  sent  to  standard  output,  and  may  lode  like 
this: 


GlSDBASE=Aisr/grass4/data 
LOG  A  nON_NAME=spearfish 
MAPSET =PERMANENI 

In  this  example,  the  full  path  name  of  the  user’s  current  location  (i.e.,  $L0CATlON_NAME)  is 

Aisr/grass4/data/spearfish,  and  the  full  path  name  of  the  user’s  current  mapset  (i.e.,  SMAPSET)  is 

Aisr/g  rass4  /data/ spearfi  sh/PI  -KM  ANENT. 

If  the  user  specifies  a  variable  name  on  the  command  line  (eg.,  g-gisenv  MAPSET),  only  the  value 

for  that  particular  GRASS  variable  is  output  to  standard  output.  Possible  variable  names  depend  on  the 

user’s  system. 

While  other  variables  may  be  associated  with  each  GRASS  session  (eg.,  DIGITIZER,  PAINTER, 

DISPLAY,  and  other  variables),  those  stated  below  are  essential. 

GISDBASE  The  SGISDBASE  is  a  directory  in  which  all  users’  GRASS  data  are  stored.  Within  the 
SGISDBASE,  data  are  segregated  into  subdirectories  (called  "locations")  based  on  the  map 
coordinate  system  used  and  the  geographic  extent  of  the  data.  Each  "location"  directory  itself 
contains  subdirectories  called  "mapsets";  each  "mapset"  stores  "data  base  elements"  —  the 
directories  (eg.,  the  cell,  cellhd,  dig,  etc.,  directories)  in  which  GRASS  data  files  are  actually 
stored. 

LGCAnON  NAME  -  The  user  must  choose  to  work  with  the  data  under  a  single  GRASS  location 
within  any  given  GRASS  session;  this  location  is  then  called  the  current  GRASS  location, 
and  is  specified  by  the  variable  SIXK'ATION_NAME.  The  $LOCATION_NAME  is  the 
GRASS  data  base  fixation  whose  data  will  be  affected  by  any  GRASS  commands  issued 
during  the  user’s  current  GRASS  session,  and  is  a  subdirectory  of  the  current  SGISDBASE. 
Each  location"  directory  can  contain  multiple  "mapset"  directories  (including  the  special 
mapset  "PERMANENT').  Maps  stored  tuxler  the  same  GRASS  lXXATION_NAME  (and/or 
within  the  same  MAl’SEl)  must  use  the  same  coordinate  system  and  typically  fall  within  the 
Ixxindarics  of  the  same  geographic  region  (aka,  "location"). 

MAP  SEP  Each  "mapset"  contains  a  set  of  maps  relevant  to  the  L0CAT10N_NAME  directory  in 
which  it  appears.  Each  I  /  X'AIK )N  NAME!  can  contain  multiple  mapsets.  (Majisels  which 
fall  under  the  same  I  XX'ATION_NAME  all  contain  data  geographically  relevant  to  the 
IXX  ATK  )N__NAM1  ,  anti  till  store  data  in  the  same  map  coordinate  system.  Frequently,  maps 
tire  placed  into  different  mapsets  to  distinguish  file  ownership  eg.,  each  user  might  have  his 
own  mapset,  storing  any  maps  that  lie  has  created  and/or  are  relevant  to  his  work.)  During  each 
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GRASS  session,  tlie  user  must  choose  one  mapset  It)  lx:  the  current  mapset;  the  current 
mapset  setting  is  given  by  SMAPS1T,  and  is  a  subdirectory  of  SI  /  X'ATION_NAME„  I  Airing 
a  single  GRASS  session,  the  user  can  use  available  data  in  any  of  the  mapsets  stored  under  the 
current  1 .( )CATION_N  AME  directory  that  are  in  the  user’s  mapset  search  path  and  accessible 
by  the  user.  1  lowever,  within  a  single  GRASS  session,  the  user  only  has  write  access  to  data 
stored  under  the  current  mapset  (specified  by  the  variable  SMAPSET). 

Each  "mapset"  stores  GRASS  data  base  elements  (i.e.,  the  directories  in  which  GRASS  data 
files  are  stored).  Any  maps  created  or  modified  by  the  user  in  the  current  GRASS  session  will 
be  stored  here.  The  M/M’SFT  directory  "PERMANENT'  is  generally  reserved  for  the  set  of 
maps  that  form  the  base  set  for  all  users  working  under  each  l/X'AnON_NAME. 

Once  w  ithin  a  GRASS  session,  GlvASS  users  have  access  only  to  the  data  under  a  single  GRASS  data 
base  directory  (the  current  GRASS  data  base,  specified  by  the  variable  SGISDBASE),  and  to  a  single 
GRASS  location  directory'  (the  current  location ,  specified  by  the  variable  SLOCAllON^NAME). 
Within  a  single  session,  the  user  may  only  modify  the  data  in  the  current  mapset  (specified  by  the 
variable  $  MAPSET),  but  may  use  data  available  under  other  mapsets  under  the  same 
IjOCAIIONNAME. 

A1  of  these  names  must  be  legal  names  on  tlie  user  s  current  sy  stem.  1  or  UNIX  users,  names  of  fewer 
than  14  characters  and  containing  no  non-printing  or  spue  axles  are  pemiissible.  Examples  of 
permissible  names  include:  one,  mymap,  VeGejmap,  and  l_for_me.  The  underscore  character  can 
safely  be  used  in  place  of  a  blank  for  multiple-word  names. 

NOTES 

The  output  from  g.gisenv  when  invoked  witluxit  arguments  is  directly  usable  by  /bin/sh.  Ihe  following 
command  will  cast  each  variable  into  the  UNIX  environment: 

eval  g.gisenv' 

This  works  only  for  /bin/sh.  Ihe  format  of  the  output  is  not  compatible  with  other  UNIX  shells. 

SEE  ALSO 

g.access,  g.ask,  g.filename,  g.findfile,  g.mapsets 

AUTHOR 

Michael  Shapiro,  U  S.  Army  Construction  Engineering  Research  I  aboratory 
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NAME 

gJtelp  ~  GRASS  help  facility. 

(GRASS  Help  Program) 

SYNOPSIS 

giielp 

DESCRIPTION 

g.help  provides  the  user  with  functional  information  on  GRASS  programs,  a  glossary,  and  access  to 
on-line  User’s  Reference  Manual  entries.  The  help  facility  is  accessed  by  simply  typing  giielp  on 
the  command  line.  The  user  can  then  wend  his  way  through  a  series  of  menus  (organized  by  functional 
area)  and  key-word  searches. 

Ch-line  reference  manual  entries  can  also  be  accessed  directly,  through  the  GRASS  gjnanual 
command. 

SEE  ALSO 

GRASS  User’s  Reference  Manual 
g. manual 
AUTHORS 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory 
Kurt  Buehler,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Dsborah  Brinegar,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Mary  Martin,  U.S.  Army  Construction  Engineering  Research  Laboratory 

Note.  The  help  facility  uses  the  hyper  program  written  by  James  Westervelt.  This  program  has  been 
upgraded  by  Kurt  Buehler. 
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NAME 

g.list  -  Lists  available  GRASS  data  base  files  of  the  user-specified  data  type  to  standard  output. 
(GRASS  File  Management  Program) 

SYNOPSIS 

gJist 

g.list  help 

gJist  [-f]  type  ^datatype  [mapset  =name) 

DESCRIPTION 

g.list  allows  the  user  to  list  user- specified,  available  and  accessible  files  front  mapsets  under  the  user’s 
current  location.  When  invoked  simply  as  gJist,  the  program  prompts  the  user  for  the  type  of  data  to 
be  listed  from  all  mapsets  in  the  user’s  current  mapset  search  path.  The  user  can  list  files  from  a 
mapset  not  listed  in  the  current  mapset  search  path  by  running  the  program  non-interactivelv,  specifying 
the  (optional)  flag  setting  and  parameter  values  on  the  command  line.  Program  flag  and  parameters  arc 
described  below. 


Flag: 

-f  Returns  a  verbose  file  listing  that  includes  map  titles. 


Parameters: 
type  ^datatype 


The  type  of  data  to  be  listed. 
Options:  (listed  in  bold) 

Raster  files 


rast 

vect 

icon 

labels 

ates 

region 

group 


Binary  vector  files 
Paint  icon  files 
Paint  labels  files 
Site  list  file.. 

Region  definition  files 
Imagery  group  files 


mapset  =name  The  name  of  a  mapset  to  be  searched  for  files  of  the  specified  type.  Any  mapset 
name  under  the  current  location,  v. he t her  or  not  it  is  listed  in  the  user’s  current 
mapset  search  path,  can  be  specified. 

Default:  If  unspecified,  files  of  the  specified  type  from  all  mapsets  in  the  user’s 
current  search  path  will  be  listed  to  standard  output. 

NOTES 

If  the  user  requests  that  files  from  a  mapset  to  which  access  has  lieen  icstricted  be  listed  (sec  g. access). 
no  files  from  this  mapset  will  be  listed. 

SEE  ALSO 

g. access,  g.mapsets 

AUTHOR 

Michael  Shapiro,  US.  Army  (jonstmetion  Engineering  Research  laboratory 
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NAME 

g. manual  -  Accesses  GRASS  User*  s  Reference  Manual  entries. 

(GRASS  File  Management  Program) 

SYNOPSIS 

gjnannal 
gjnannal  help 

gjnannal  [-laefs]  [tntri*&=name[,name,...]\ 

DESCRIPTION 

The  g manual  command  provides  user  access  to  the  on-line  GRASS  User’s  Reference  Manual 
entries.  The  user  may  request  a  list  of  available  manual  entries,  and  may  get  a  manual  entry  printed  to 
the  terminal  screen  and/or  to  the  line  printer. 

g. manual  can  be  run  either  interactively  or  non-interactively.  If  the  user  types 

gjnannal 

on  the  command  line  without  program  arguments,  the  program  will  prompt  the  user  for  a  manual  entry 
to  display.  The  user  may  enter  "list”  to  get  a  section- by- section  listing  of  the  manual  entries  available. 
Once  the  user  has  viewed  the  desired  information,  it  may  be  printed  by  responding  to  the  questions 
appropriately. 

The  user  can  run  the  program  non-interactively,  by  specifying  the  appropriate  options  and/or  the 
name( s)  of  the  manual  entries  to  displayed. 

OPTIONS 

-1  This  option  will  list  all  manual  entries,  one  per  line. 

-a  This  option  will  list  all  manual  entries  in  a  more  appealing  format.  The  manual  page  list  will 

be  separated  by  manual  section. 

-«  This  option  tells  g manual  to  ignore  empty  manual  sections  when  printing  the  listings  from  die 
-1  or  -a  options. 

-f  This  option  will  add  formfeeds  to  output  listing  when  using  the  -a  option. 

-s  This  option  will  cause  g manual  to  run  silently.  Instead  of  displaying  the  manual  page  it  will 

simply  set  the  exit  status  to: 

0  if  entry  exists,  or 
1  if  it  does  not  exist. 

These  entries  may  also  be  accessed  through  the  g.help  command. 

SEE  ALSO 

GRASS  User’s  Reference  Manual 
ghelp 
AUTHOR 

Kurt  Buehler,  U.S.  Army  G'nstmctiou  Engineering  Research  Laboratory 
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NAME 

gjnapsets  -  Modifies  the  user’s  current  mapset  search  path,  affecting  the  user’s  access  to  data  existing 
under  the  other  GRASS  mapsets  in  the  current  location. 

(GRASS  File  Management  Program) 

SYNOPSIS 

gjmapsets 
gjnapsets  help 

gjmapsets  [-Ip]  [mapset  =name[/tame,...]\ 

DESCRIPTION 

A  mapset  holds  a  distinct  set  of  data  layers,  each  relevant  to  the  same  (or  a  subset  of  the  same) 
geographic  region,  and  each  drawn  in  the  same  map  coordinate  system.  At  the  outset  of  every  GRASS 
session,  the  user  identifies  a  GRASS  data  base,  location,  and  mapset  that  are  to  be  the  user’s  current 
data  base,  current  location,  and  current  mapset  for  the  duration  of  the  session;  any  maps  created  by 
the  user  during  the  session  will  be  stored  under  the  current  mapset  (SMAPSEr)  set  at  the  session’s 
outset. 

The  user  can  add,  modify,  and  delete  data  layers  that  exist  under  his  current  mapset.  Although  the 
user  can  also  access  (i.e.,  use)  data  that  are  stored  under  other  mapsets  in  the  same  GRASS  location, 
the  user  can  only  make  permanent  changes  (create  or  modify  data)  located  in  the  current  mapset.  The 
user’s  mapset  search  path  lists  the  order  in  which  other  mapsets  in  the  same  GRASS  location  can  be 
searched  and  their  data  accessed  by  the  user.  The  user  can  modify  the  listing  and  order  in  which  these 
mapsets  are  accessed  by  modifying  the  mapset  search  path;  this  can  be  done  asing  the  g.mapsets 
command.  Tliis  program  allows  the  user  to  use  other’s  relevant  map  data  without  altering  the  original 
data  layer,  and  without  taking  up  disk  space  with  a  copy  of  the  original  map. 

g.mapsets  shows  the  user  available  mapsets  under  the  current  GRASS  location,  lists  mapsets  to  which 
the  user  currently  has  access,  and  lists  the  order  in  which  accessible  mapsets  will  be  accessed  by 
GRASS  programs  searching  for  data  files.  The  user  is  then  given  the  opportunity  to  add  or  delete 
mapset  names  from  his  search  path,  or  modify  the  order  in  which  mapsets  will  lie  accessed. 

When  the  user  specifies  the  name  of  a  data  base  element  file  (eg.,  a  particular  vector  file,  raster  file, 
imagery  group  file,  etc.)  to  a  GRASS  program,  the  prognun  searches  for  the  named  file  under  each  of 
the  mapsets  listed  in  the  user’s  mapset  search  path  in  the  order  listed  there  until  the  program  finds  a  file 
of  the  given  name.  (Users  can  also  specify  a  file  by  its  mapset,  to  make  explicit  the  mapset  from  which 
the  file  is  to  be  drawn;  c.g.,  the  command: 

g.copy  rsst  soils.  file@PERM  AIN  ENT’ jny. soils 

ensures  that  a  new  file  named  my. soils  is  to  be  a  copy  of  the  file  soils.file  from  the  mapset 
PERMANENT.) 

It  is  common  for  a  user  to  have  the  special  mapset  PERMANENT  included  in  his  mapset  search  path, 
as  this  mapset  typically  contains  finished  base  maps  relevant  to  many  applications.  Often,  other 
mapsets  which  contain  sets  of  interpreted  map  layers  will  be  likewise  included  in  the  user's  inapset 
search  path.  Suppose,  for  example,  that  the  mapset  Soil_Maps  contains  interpreted  soils  map  layers  to 
which  the  user  w'ants  access.  The  mapset  Soil_Maps  should  then  be  included  in  the  user’s 
search  path  variable. 

The  mapset  search  path  is  saved  as  part  of  the  current  mapset.  When  the  user  works  with  that  inapset 
in  subsequent  GRASS  sessions,  the  previously  saved  mapset  search  path  will  lx;  used  (and  w  ill  continue 
to  be  used  until  it  is  modified  by  the  user  with  g.mapsets). 
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Flags: 

-I  List  all  available  mapsets  under  the  user’s  current  location. 

-p  Print  the  user’s  current  mapset  search  path  to  standard  output 

Parameter: 

mapset  =name[/iame,...)  Name(s)  of  existing  GRASS  mapset(s)  under  the  current  location. 

g.mapsets  sets  the  current  mapset  search  path  to  the  mapsets  named  on  the  command  line.  If 
g .mapsets  is  typed  but  no  mapset  names  are  specified  by  the  user  on  the  command  line,  the  program 
will  print  the  user’s  current  mapset  search  path,  list  available  mapsets,  and  prompt  the  user  for  a  new 
mapset  search  path  listing . 

NOTES 

Users  can  restrict  others’  access  to  their  mapset  files  through  use  of  the  GRASS  program  g. access. 
Mapsets  to  which  access  is  restricted  can  still  be  listed  in  another’s  mapset  search  path;  however,  access 
to  these  mapsets  will  remain  restricted. 

SEE  ALSO 

g.access,  g.copy,  g.gisenv,  g.list 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

g.region  -  Program  to  manage  the  boundary  definitions  for  the  geographic  region. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g-regian 
g .region  help 

g.region  f-dgpa]  [region  =name]  [raster  =name]  [vector  name]  [utes=name]  [n  =value]  [s=va/ue| 
[e=value\  [w  =value]  [res=va/ue]  [nsres=v a/ue]  [ewres=va/ue}  [loam  name] 

[align  name]  [sa ve=name\ 

DESCRIPTION 

The  g.region  program  allows  the  user  to  manage  the  settings  of  the  current  geographic  region.  These 
regional  boundaries  can  be  set  by  the  user  directly  and/or  set  from  a  region  definition  file  (stored  under 
the  windows  directory  in  the  user’s  current  mapset).  The  user  can  create,  modify,  and  store  as  many 
geographic  region  definitions  as  desired  for  any  given  mapset.  However,  only  one  of  these  geographic 
region  definitions  will  be  current  at  any  given  moment,  for  a  specified  mapset;  i.e.,  GRASS  programs 
that  respect  the  geographic  region  settings  will  use  the  current  geographic  region  settings. 

INTERACTIVE  PROGRAM  USE:  MAIN  MENU 

The  main  menu  consists  of  an  information  section  listing  the  current  GRASS  data  base  LOCATION, 
MAPSET,  and  CURRENT  REGION,  followed  by  user  options: 


LOCATION:  sample 

REGION  FACE  JIT 

CURRENT  REGION: 

PROJECTION:  1  (UTM) 
ZONE:  13 

N=5 167600 
E=729314 

S=5156755  RES=50  ROWS=216 
W=705924  RES=50  COLS=467 

Please  select  one  of  the  following  options 

Current  Region 

Region  Database 

1  Modify  current  region 
directly 

6  Save  current  region  in 
the  database 

2  Set  from  default  region 

7  Create  a  new  region 

3  Set  from  a  database 
region 

8  Modify  an  existing  region 

4  Set  from  a  raster  map 

5  Set  from  a  vector  map 

RETURN  to  quit 

DEFINITIONS 

Region: 

Here,  a  region  refers  to  a  geographic  area  with  some  defined  boundaries,  Ixised  on  a  specific 
map  coordinate  system  and  map  projection.  Each  region  also  has  associated  with  it  the  specific 
east-west  and  north- south  resolutions  of  its  smallest  units  (rectangular  units  called  "cells") 
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The  region’s  boundaries  are  given  as  the  northernmost,  southernmost,  easternmost,  and 
westernmost  points  that  define  its  extent.  The  north  and  south  boundaries  are  commonly  called 
northings,  while  the  east  and  west  boundaries  are  called  eastings. 

The  region’s  cell  resolution  defines  the  size  of  the  smallest  piece  erf  data  recognized  (imported, 
analyzed,  displayed,  stored,  etc.)  by  GRASS  programs  affected  by  the  current  region  settings. 
The  north-south  and  east-west  cell  resolutions  need  not  be  the  same,  thus  allowing  non-square 
data  cells  to  exist. 

Default  Region: 

Each  GRASS  LjOCA nON_N AME  has  a  fixed  geographic  region,  called  the  default  geographic 
region  (stored  in  the  region  file  DEFAULT_WIND  under  the  special  mapset  PERMANENI), 
that  defines  the  extent  of  the  data  base.  While  this  provides  a  starting  pant  for  defining  new 
geographic  regions,  user-defined  geographic  regions  need  not  fall  within  this  geographic  region. 

Current  Region: 

Each  mapset  has  a  current  geographic  region.  This  region  defines  die  geographic  area  in  which 
all  GRASS  displays  and  analyses  will  be  done.  Data  will  be  resampled,  if  necessary,  to  meet 
the  cell  resolutions  of  the  current  geographic  region  setting. 

Region  Data  Base: 

Each  GRASS  MAPSET  may  contain  any  number  erf  pre-defined,  and  named,  geographic 
regions.  These  region  definitions  are  stored  in  the  user’s  current  mapset  location  under  the 
windows  directory  (also  referred  to  as  the  user’s  data  base  of  region  definitions).  Any  of  these 
pre  defined  geographic  regions  may  be  selected,  by  name,  to  become  the  current  geographic 
region.  Users  may  also  access  saved  region  definitions  stored  under  other  mapsets  in  the 
current  location,  if  these  mapsets  are  included  in  the  user’s  mapset  search  path. 

REGION  EDIT  PROMPT 

Most  of  the  options  will  require  the  user  to  edit  a  geographic  region,  be  it  the  current  geographic  region 
or  one  stored  in  the  user’s  data  base  of  region  definitions  (the  windows  directory).  A  standard  prompt 
is  used  to  perform  this  edit.  An  example  is  shown  below: 
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g. region 


DlENTIFY  FKHCN 


Def  \test: 
233975 .00 


CEFAJ.T  RB3KN 


Efefaul t  North:  3402025.00 


=\CLR  REGICN= 
5CKIH  HHE 
3402025. 00_ 


[WEST  EDGE 
233975.00. 


SGUm  EDGE 
3399975.00. 


EAST  EDGE 
236025.00. 


Default  South:  3399975.00 


Def .East : 
236025.00 


Default  GRID  RE9CLUnCN  Region 
50.00  ---  East -Wfest  ---  50.00_ 

50.00  --  North-South  --  50.00_ 


AFTER  (IMTI  XIKi  ALL  /NSWRS,  HIT  <ESO  TO  GCNITPLH 


The  fields  NORTH  EDGE,  SOUTH  EDGE,  WEST  EDGE  and  EAST  EDGE,  arc  the  boundaries  of  the 
geographic  region  that  the  user  can  change.  The  fields  Default  North,  Default  South,  Def  West  and  Def 
East  are  the  boundaries  of  the  default  geographic  region  that  are  displayed  for  reference  and  cannot  be 
changed.  The  two  GRID  RESOLUTION  Region  fields  (east  west,  and  north-south)  are  the  geographic 
region’s  cell  resolutions  that  the  user  can  change.  The  two  GRID  RESOLUTION  Default  fields  list  the 
resolutions  of  the  default  geographic  region;  these  are  displayed  for  reference  and  cannot  be  changed 
here  by  the  user. 

REGION  MANAGEMENT  MENU  OPTIONS 

1  Modify  the  current  geographic  region  directly 

Allows  the  user  to  edit  the  current  region. 

2  Set  current  geographic  region  from  default  region 

Copies  the  default  region  to  the  current  geographic  region,  and  then  lets  the  user  edit  the 
current  geographic  region. 

3  Set  current  geographic  region  from  a  data  base  geographic  region 

Allows  the  user  to  select  a  geographic  region  by  name  from  the  data  base  of  geographic 
regions  to  become  the  current  geographic  region,  and  then  lets  the  user  edit  the  current 
geographic  region. 

Note:  geographic  region  definition  files  may  be  selected  from  other  mapsets  as  well,  if 
accessible  and  in  the  user’s  mapset  search  path. 

4  Set  current  geographic  region  from  a  raster  (cell)  map  layer 

Allows  the  user  to  select  a  raster  map  layer,  copies  the  cell  header  for  this  map  layer  to  the 
current  geographic  region,  and  then  lets  the  user  edit  the  current  getigraphic  region.  This 
option  is  useful  when  subsequent  GRASS  operations  will  lx:  used  to  jmxluce  a  raster  map  lay  er 
from  one  input  raster  map  layer  and  it  is  necessary  that  the  result  coincide  with  the  input  raster 
map  layer. 
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5  Save  the  current  geographic  region  (window)  in  the  data  base 

Allows  the  user  to  save  the  current  geographic  region  settings  in  the  user's  data  base  of  such 
settings.  These  files  are  stored  in  the  windows  directory  under  the  user’s  current  mapset.  This 
option  is  useful  when  the  current  geographic  region  is  set  directly  using  option  2,  or  even  by 
another  GRASS  program  (eg.,  d.display).  This  option  installs  an  otherwise  temporary 
geographic  region  setting  into  the  geographic  region  definition  data  base  for  recall  when 
needed. 


6  Create  a  new  data  base  geographic  region  setting 

Creates  a  new  geographic  region  definition  in  the  user’s  data  base  of  such  settiigs  in  the 
windows  directory  under  the  current  mapset,  using  the  geographic  region  edit  prompt  described 
above.  After  the  geographic  region  definition  is  created,  the  user  is  asked  if  this  geographic 
region  setting  should  also  be  used  as  the  current  geographic  region. 

7  Modify  a  data  base  geographic  region  setting 

Modifies  a  geographic  region  setting  (in  the  data  base  of  such  settings  in  the  windows 
directory  of  the  current  mapset),  using  the  geographic  region  edit  prompt.  After  the  changes 
have  been  made,  the  user  is  asked  if  this  geographic  region  setting  should  also  be  used  as  the 
current  geographic  region. 


NON-INTERACTIVE  PROGRAM  USE 

Alternately,  the  user  can  modify  the  settings  of  the  current  geographic  region  by  specifying  all  needed 
parameters  on  the  command  line.  The  user  enters  the  command  g  .region  par  ms,  where  parms  are  the 
following  parameters  and/or  flags: 

Flags: 


-d 

-8 

P 

-u 

Parameters: 


Set  current  region  settings  equal  to  default  region  settings. 

Print  the  current  region  settings  (shell  script  style)  in  a  format  that  can  be  given 
back  to  g.region  on  its  command  line. 

Print  the  current  region  settings. 

Do  not  update  the  current  region  file  settings.  Allows  die  user  to  temporarily  use 
a  different  region  setting,  without  saving  this  setting. 


region  name 
raster  name 

vector  name 
sites  =name 

upvalue 

s^value 

*=value 

w=value 

rts=value 

nsrr-s-value 

trwrts=value 

zoom  name 


Make  current  region  settings  same  as  the  named  region  file  settings 

Make  current  region  settings  same  as  those  in  the  named  raster  map’s  cell  header. 
But  see  zoom  =name  option,  below. 

Make  the  current  region  settings  the  same  as  those  of  die  named  vector  map. 

Set  the  current  region  to  the  smallest  region  encompassing  all  coordinates  in  the 
named  sitejists  file,  aligned  with  the  current  region. 

Set  map  coordinate  value  for  the  region’s  northern  edge  to  x 
Set  map  coordinate  value  for  the  region’s  southern  edge  to  x 
Set  map  coordinate  value  for  the  region’s  eastern  edge  to  x 
Set  map  coordinate  value  for  the  region’s  western  edge  to  x 
Set  grid  resolution  (both  north-south  and  east-west)  to  x 
Set  north-south  grid  resolution  value  to  x 
Set  east-west  grid  resolution  value  to  x 

Set  current  region  settings  to  the  smallest  region  encompassing  all  non-zero  data 
in  the  named  raster  map  layer  that  fall  inside  the  user’s  current  region. 

If  the  user  also  includes  the  raster  =name  option  on  the  command  line, 
zoom  name  will  set  the  current  region  settings  to  the  smallest  region 
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encompassing  all  non-zero  data  in  the  named  zoom  map  that  fall  inside  the 
region  stated  in  the  cell  header  for  the  named  raster  map. 

align  =73 time  Set  the  current  resolution  equal  to  that  of  the  named  raster  map,  and  align  the 

current  region  to  a  row  and  column  edge  in  the  named  map.  Alignment  only 
moves  the  existing  region  edges  outward  to  the  edges  of  the  next  nearest  cell  in 
the  named  raster  map  -  not  to  the  named  map’s  edges.  To  perform  the  latter 
function,  use  the  raster=name  option. 

save  =name  Save  current  region  settings  in  the  named  region  file 

EXAMPLES 

g.region  n  =7360100  e  =699000 

w  ill  reset  the  northing  and  easting  for  the  current  region,  but  leave  the  south  edge,  west  edge, 
and  the  region  cell  resolutions  unchanged. 

g. region  -dp  s  =698000 

will  set  the  current  region  from  the  default  region  for  tlie  GRASS  data  bast'  location,  reset  the 
south  edge  to  698000,  and  then  print  the  result. 

g. region  n  n-HOOO  w=w500 

The  upvalue  may  also  be  specified  as  a  function  of  its  current  value:  n=n lvalue  increases 
the  current  northing,  while  n=nvalue  decreases  it.  This  is  also  tme  for  s  =value,  e  ==value ,  and 
w  = value.  In  this  example  the  current  region’s  northern  bound: try  is  extended  by  1000  units 
and  the  current  region’s  western  boundary  is  decreased  by  500  units. 

g. region  n  -S-H000  e=wH000 

This  form  allows  the  user  to  set  the  region  boundary  values  relative  to  one  another.  Here,  the 
northern  boundary  coordinate  is  set  equal  to  1000  units  Iaiger  than  the  southern  boundary’s 
coordinate  value,  and  the  eastern  boundary’s  coordinate  value  is  set  equal  to  1000  units  larger 
than  the  western  boundary’s  coordinate  value.  The  corresponding  forms  s=n -value  and 
w  =e  value  may  be  used  to  set  the  values  of  the  region’s  southern  and  western  boundaries, 
relative  to  the  northern  and  eastern  boundary  values. 

g.region  raster  =soils 

This  form  will  make  the  current  region  settings  exactly  the  same  as  those  given  in  the  cell 
header  file  for  the  raster  map  layer  soils. 

g.region  raster  —soils  zoom=soils 

This  form  will  first  look  up  the  cell  header  file  for  the  raster  map  layer  soils,  use  this  as  the 
current  region  setting,  and  then  shrink  the  region  down  to  the  smallest  region  which  still 
encompasses  all  non-zero  data  in  the  map  layer  soils.  Note  that  if  the  parameter  raster  =soils 
were  not  specified,  the  zoom  would  move  to  encompass  all  non-zero  data  values  in  the  soils 
map  that  were  located  within  the  current  region  setting. 

g -region  -up  raster  =soils 

The  -u  option  suppresses  the  re  setting  of  the  current  region  definition.  This  can  be  useful 
when  it  is  desired  to  only  extract  region  information.  In  this  case,  the  cell  header  file  fix  the 
soils  map  layer  is  printed  without  changing  the  current  region  settings. 

g.region  -u  raster  =soils  zoom=soils  save=soils 

This  will  zoom  into  the  smallest  region  that  encompasses  all  non- zero  soils  data  values,  and 
save  the  new  region  settings  in  a  file  to  be  allied  soils  and  stored  under  the  windows  directixy 
in  the  user’s  current  inapsct.  The  current  region  settings  are  not  changed. 
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g-region  -p 

This  will  print  the  current  region  in  the  format: 


projection: 

1  (UTM) 

zone: 

15 

north: 

4294050.00 

south: 

4249950.00 

east: 

526050.00 

west: 

500950.00 

nsres: 

100.00 

ewres: 

100.00 

rows: 

441 

cols: 

251 

g  .region  -g 

The  -g  option  prints  the  region  in  the  following  formal: 

n=4294050.00 
s  =4249950 .00 
e  ==526050 .00 
w  =500950 .00 
nsres=100.00 
ewres=100.00 


This  format  does  not  have  the  rows  and  columns,  but  can  be  fed  bade  into  g. region  on  its 
command  line. 

The  -p  (or  -g)  option  is  recognized  last.  This  means  that  all  changes  are  applied  to  die  region 
settings  before  printing  occurs. 

NOTE 

After  all  updates  have  been  applied,  the  current  region’s  southern  and  western  boundaries  are  (silently) 
adjusted  so  that  the  north/south  distance  is  a  multiple  of  the  north/south  resolution  and  that  the  eastAvest 
distance  is  a  multiple  of  the  eastAvest  resolution. 

SEE  ALSO 

d.display,  djoom,  g. access,  g.mapsets 

AUTHOR 

Michael  .Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

g. remove  -  Removes  data  base  element  files  from  the  user’s  current  niapsct. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g.remove 
g.remove  help 

g.remove  [rast=name[/iame,...]\  [vect=name[nonie  [icon  =name[ name ....[]  [ label s=mame[name, 
[siies=name[/iome,...]]  [rcg\oR=name\name ,...\\  \graup=nanu\ jiame ,...]] 

DESCRIPTION 

g.remove  allows  the  user  to  remove  specified  data  Ixise  element  files  from  the  current  mapset.  If 
g.remove  is  invoked  without  arguments  on  the  command  line,  a  menu  will  ap|x;tr  listing  jrossible  data 
element  types,  as  below : 

1  raster  maps 

2  vector  maps 

3  paint  icon  files 

4  paint  label  files 

5  site  list  files 

6  region  files 

7  imagery  group  files 
RETURN  to  exit 

Once  the  element  type  is  selected,  the  user  is  prompted  to  name  a  sjxcific  file  of  this  element  type  for 
removal.  (This  list  will  vary,  depending  on  what  files  currently  exist  in  the  user's  mapset.)  The 
specified  file  is  removed,  and  the  user  is  again  prompted  for  the  name  of  a  file  of  this  element  type  to 
be  removed.  When  prompted  for  a  file  name,  the  user  may  enter  list  to  see  a  list  of  existing  files  of 
this  element  type,  or  hit  RETURN  to  get  l rack  to  the  above  menu. 

Alternately,  the  user  can  specify  the  data  base  element  type  ;uxl  lile(s)  to  lx*  removed  on  the  command 
line.  Data  base  element  types  ;ire  specified  by  the  names  to  the  left,  below. 

Parameters: 

rast  name) name,...]  Name(s)  of  raster  file(s)  to  lx  removed. 

yect=name\name ,...}  Name(s)  of  vector  file(s)  to  lx  removed, 

icon  name [  name ,. .. ]  Name(s)  of  paint  icon  lile(s)  to  lx  removed. 

label s=name[ name,...]  Natne(s)  of  paint  labels  file(s)  to  be  removed, 
sites  =/ia/ne[  name,...]  Name(s)  of  site  list  file(s)  to  lx  removed, 

region  =oiame[name,...]  Name(s)  of  region  file(s)  to  be  removed. 
groap=name[name,..  \  Name(s)  of  imagery  group  file(s)  to  be  removed. 

The  data  base  elenxnt  file(s)  named  by  the  user  on  tlx  command  line  are  subsequently  removed  from 
the  user’s  current  mapset. 

EXAMPLE 

for  example,  the  below  command  will  cause  the  raster  files  named  sails,  slope,  and  temp,  the  vector 
files  named  roads  and  rail,  and  the  imagery  group  files  named  nhap.l  and  nhap.2,  and  these  files' 
assrxiated  support  files  (eg.,  cell  header  files,  category  files,  etc.),  to  lx  removed  from  the  user's 
current  mapset. 

g.remove  rast  =soils,slope, temp  vect  =road  vail  group  =nhap.l,nhap.2 
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NOTE 

If  a  particular  data  base  element  file  has  support  files  associated  with  it  (eg.,  as  is  commonly  the  case 
with  raster  files),  g. remove  will  remove  these  support  files  along  with  the  data  base  element  file 
specified. 

The  user  can  only  use  g.remove  to  remove  data  files  existing  under  the  user’s  current  mapset. 

FILES 

SGISBASEJetc/element  Jist  lists  the  element  types  whose  files  can  be  removed  ty  the  user. 

SEE  ALSO 

g.copy,  g.list,  g.rename 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

g. rename  -  To  rename  data  base  element  files  in  the  user’s  current  mapset. 

(GRASS  File  Management  Program) 

SYNOPSIS 

gjrename 
g.rename  help 

g.rename  [rast  =old,new]  [vect  =old,new]  [icon  =old,new\  [Iabels=o/d,neM'l  l>ites=o/d,neK'] 
[region  =old,new]  [group  =old,new] 

DESCRIPTION 

g. rename  allows  the  user  to  rename  data  base  element  files  in  the  user’s  current  majiset.  The  user  can 
specify  all  necessary  infonnation  to  g.rename  on  the  command  line,  by  specifying:  the  type  of  data 
base  element  to  be  renamed  (one  or  more  of:  rast,  vect,  icon,  labels,  9tes,  region,  and  group);  the 
specific  file  element  in  the  current  mapset  to  be  renamed  (old)’,  and  the  new  name  to  be  assigned  to  this 
file  element  (new)  in  the  current  mapset.  'lhe  file  element  old  is  then  renamed  to  new. 

Users  can  also  simply  type  g.rename  without  arguments  on  the  command  line,  to  receive  a  menu  of 
existing  data  base  element  types  and  files  from  which  to  choose  for  possible  renaming: 

1  raster  maps 

2  binary  v  ector  maps 

3  paint  icon  files 

4  paint  label  files 

5  site  list  files 

6  region  definition  files 

7  imagery  group  files 
RETURN  to  exit 

NOTE 

If  a  data  base  clement  has  supjxirt  files  (e.g.,  as  is  commonly  the  case  with  raster  files),  these  support 
files  also  are  renamed. 

If  the  user  attempts  to  rename  a  file  to  itself  by  setting  the  new  file  name  equal  to  the  old  file  name 
(e.g.,  gj-ename  rast=soils,sotls),  g.rename  will  not  execute  the  rename,  but  instead  state  that  no 
rename  is  needed.  However,  g.rename  will  allow  the  user  to  overwrite  other  existing  files  in  the 
current  mapset  by  making  the  new  file  name  that  of  an  already  existing  file. 

SEE  ALSO 

g.copy,  g.list,  g.remove 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Gmstniction  Engineering  Research  laboratory 
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NANNIE 

g.tempfile  -  Creates  a  temporary  file  and  prints  the  file  name 
(GRASS  File  Management  Program) 

SYNOPSIS 

g.tempfile  help 
g.tempfile  pid  -value 

DESCRIPTION 

g.tempfile  is  designed  for  shell  scripts  that  need  to  use  large  temporary  files.  GRASS  presides  a 
mechanism  for  temporary  files  that  does  not  depend  on  Amp.  GRASS  temporary  files  are  created  in  the 
data  base  with  the  assumption  that  there  will  be  enough  space  under  die  data  base  for  large  files. 
GRASS  periodically  removes  temporary  files  that  have  been  left  behind  by  programs  that  failed  to 
remove  them  before  terminating. 

g.tempfile  creates  an  unique  file  and  prints  the  name.  The  user  is  required  to  provide  a  process-id  which 
will  be  used  as  part  of  the  name  of  the  file.  Most  Unix  shells  provide  a  way  to  get  the  process  id  erf 
the  current  shell.  For  /bin/sh  and  Arin/csh  this  is  $$.  It  is  recommended  that  $$  be  specified  as  the 
process-id  for  g.tempfile 

EXAMPLE 

For  /bin/sh  scripts  the  following  syntax  should  be  used: 

tempi  =' g.tempfile  pid=$$' 
temp2=  g. tempfile  pid=$$' 

For  /bin/esh  scripts,  the  following  can  be  used: 

set  tempi  =' g.tempfile  pid=$$' 
set  temp2=  g.tempfile  pid=$$' 

NOTES 

Each  call  to  g. tempfile  creates  a  different  (i.e.,  unique)  name. 

Although  GRASS  does  eventually  get  around  to  removing  tempfiles  that  have  been  left  behind,  the 
programmer  should  make  every  effort  to  remove  these  files.  They  often  get  large  and  take  up  disk 
space.  If  you  write  /bin/sh  scripts,  learn  to  use  the  /bin/sh  trap  command.  If  you  write  bin/esh  scripts, 
leam  to  use  the  /bin/esh  onintr  command. 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

g.version  -  Outputs  the  GRASS  version  number  and  date. 

(GRASS  File  Management  Program) 

SYNOPSIS 

g.version 
g.version  help 

DESCRIPTION 

g.version  prints  to  standard  output  the  GRASS  version  number  and  date,  in  the  form: 

GRASS  4.0  (Summer  1991) 

NOTES 

This  program  requires  no  command  line  arguments;  the  user  simply  types  g.version  on  the  command 
line  to  see  the  version  number  and  date  of  the  GRASS  software  currently  being  run  bv  the  user. 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i.build.blk  -  An  imagery  function  that  creates  and  edits  blocks  and  sub-blocks  of  imagery  groups  for 
ortho-  rectification. 

(GRASS  Imagery  Program) 

SYNOPSIS 

i.build.blk 

DESCRIPTION 

An  imagery  photo  block  coasists  of  several  scanned  aerial  photographs  (raster  map  layers)  of  a  common 
area.  An  imagery  sub-block  is  a  subset  of  these  raster  map  layers. 

i.build.blk  allows  the  user  to  collect  one  or  more  imagery  groups  by  assigning  them  to  a  named  block 
and  sunblock.  This  enables  the  user  to  run  ortho- rectification  programs  on  a  single  imagery  group 
within  a  sub-block. 

'Ihe  user  first  creates  all  of  the  imagery  groups  using  i.group. 

Ihe  first  menu  in  the  i.build.blk  program  asks  the  user  to  select  a  block.  If  the  block  does  not  exist, 
the  user  will  be  asked  if  he  or  she  would  like  to  create  a  new  block. 


This  program  edits  blocks  of  imagery  groups  for  ortho-rectification. 

You  may  select  or  create  blocks  of  imagery  groups. 

You  may  edit  blocks  of  existing  imagery  groups. 

You  may  create  sub-blocks  of  imagery  groups  within  the  Mock. 

You  may  select  a  TARGET  location  for  the  ortho-rectified  blocks. 

You  may  select  an  elevation  data  raster  file  from  the  TARGET  location. 

You  may  select  a  camera  reference  file  for  the  block. 

Please  enter  the  block  to  be  exeat edAnodified 

BLOCK: _  (enter  ’list’  for  a  list  of  existing  blocks) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 

(OR  <Ctrl-C>TO  EXIT) 


If  the  word  list  is  entered,  blocks  that  have  already  been  created  in  the  current  LOCATION  aixi 
MAI>SEI'(S)  will  Ire  displayed. 


The  second  menu  in  i.build.blk  provides  the  user  with  the  following  options: 


1.  Select  a  different  block 

2.  Edit  block  title 

3.  Select  a  TARGET  location 

4.  Select  an  elevation  data  layer 

5.  Select  a  camera  reference  file 

6.  Include  new  imagery  groups  in  the  block 
or  remove  imagery  groups  from  the  block 

7.  Create  a  new  sub-block  within  the  block 
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RETURN  to  exit 


lhe  options  are  described  as  follows: 

Select  a  different  block 

If  option  number  1  is  chosen,  the  following  menu  is  displayed: 


Please  enter  the  block  to  be  created /modified 
BLOCK:  _  (enter  ’list’  for  a  list  of  blocks) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 

(OR  <Ctrl-C>TO  EXIT) 


If  >ne  word  list  is  entered,  blocks  that  have  already  been  created  in  the  current  I .( K'ATION 
and  MAPSFI(S)  will  be  displayed. 


lulit  block  title 

If  option  number  2  is  selected,  an  entry  space  is  provided  to  type  in  the  block  title.  This  title 
is  useful  in  identifying  each  Hock: 


TITLE 


This  option  offers  an  opportunity  to  go  back  and  cliange  the  entry  if  it  is  not  correct  by  asking: 

Look  ok?  (y/h). 

Select  a  TARGl-T  location 

If  option  number  3  is  selected,  an  entry  space  is  provided  to  type  in  the  TARGET  location  and 
mapset  were  the  ortho- rectified  raster  files  are  to  reside. 

The  following  menu  asking  for  the  target  IXX'ATFON  and  MAI ’SET  is  displayed: 


Please  select  the  target  LOCATION  and  MAPSET  for  block  <t)l ock  name > 

CURRENT  LOCATION:/oca//on _ _ _ 

CURRENT  MAPSET:  mapset _ 

TARGET  LOCATION: _ 

TARGET  MAPSET: _ 

(enter  list  for  a  list  of  locations  or  map  sets  within  a  location) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Orl-C>  TO  CANCEL) 


GRASS  4.0  (Summer  1991) 


US.  Armv  CERE 


112 


i.build.blk 


GRASS  Reference  Manual 


i.build.bik 


If  die  word  list  is  entered,  the  list  of  available  LOCATION(S)  and  MAPSET(S)  will  be 
displayed. 

Select  an  elevation  data  layer 

If  option  number  4  is  selected,  an  entry  space  is  provided  to  type  in  the  name  of  an  existing 
raster  file  within  the  TARGET  location  that  is  to  be  used  as  the  elevation  data  during  ortho- 
rectification. 

The  following  menu  asking  a  raster  file  in  the  TARGET  location  to  be  used  for  elevation  data 
is  displayed: 


Please  select  an  elevation  raster  file  for  block  <bl(x:k  name  > 

Elevation  raster  file  : _ 

(enter  list  for  a  list  of  raster  files  in  the  TARGET  location) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


If  the  word  list  is  entered,  a  list  of  raster  files  within  the  TARGET  location  will  be  displayed. 

NOTE:  It  is  assumed  that  the  category  values  of  the  selected  elevation  raster  map  layer  are 
represented  in  METERS,  rjnapcalc,  may  be  used  to  convert  other  data  conventions,  as  well  as 
replace  any  cells  with  category  value  zero  (no-data)  with  another  value. 

Select  a  camera  reference  file 

If  option  number  5  is  selected,  an  entry  space  is  provided  to  type  in  the  name  of  an  existing 
camera  reference  file  within  the  CURRENT  location  that  is  to  be  used  for  data  during  ortho¬ 
rectification. 

The  following  menu  asking  for  an  existing  camera  reference  file  is  displayed: 


Please  select  a  camera  reference  file  for  block  <blockjtame> 

Camera  reference  file  : _ 

(enter  list  for  a  list  of  existing  camera  reference  files) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>  TO  CANCEL) 


If  the  word  list  is  entered,  a  list  of  existing  camera  reference  files  be  displayed. 

NOTE:  The  GRASS  program  i.  mod. earner  a  may  be  used  to  create  camera  reference  files. 

Include  or  remove  imagery  groups  from  the  block 
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When  choosing  option  number  6,  the  following  menu  is  displayed: 


LOCATION:  location  BLOCK:  demo  MAPSET:  mapset 

If  you  wish  to  delete  an  imagery  group  from  block  {demo],  remove  the  ’x’  from  in 
front  of  the  file  name. 


x  groupI3  in  mapset 

x  groupl4  in  mapset 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  Ctrl-C>TO  CANCEL) 


Next,  a  menu  listing  ;d I  the  oilier  imagery  gnxijis  present  in  the  current  MAI’SIT(S)  will  he 
displayed: 


LOCATION:  location  BLOCK:  demo  MAPSET:  mapset 

Please  mark  an  ’x’  hy  the  imagery  groups  to  be  added  in  block  | demo\ 

MAPSET:  mapset 
x  :group21  in  mapset 
X  :group22  in  mapset 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  ESOTO  CONTINUE 
(OR  Ctrl-OTO  CANCEL) 


If  more  than  one  MAPSET  is  selected,  menus  for  those  mapsets  will  also  lx:  displayed.  All 
imagery  groups  selected  with  an  ’x’  will  be  included  in  tlie  block  being  updated. 

The  user  will  then  have  the  opportunity  to  check  the  contents  of  the  Hock  that  was  just 
modified: 


Block  [demo]  references  the  following  raster  files 


groupl3  in  mapset 
groupld  in  mapset 
groupZl  in  mapset 
group22  in  mapset 


Look  ok?  (yAi) 


If  the  user  responds  with  the  letter  y  then  the  following  sentence  is  display  ed  on  the  screen: 


Block  [demo]  updated! 
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And  the  main  menu  for  i.build.blk  returns. 

If  the  user  responds  n,  the  menu  containing  the  block  files  after  it  was  modified  will  be 
displayed  and  the  user  will  be  asked  to  place  an  x  in  front  of  those  imagery  groups  that  are  to 
be  removed  from  the  block.  'Ihen,  a  menu  listing  ail  of  the  other  imagery  groups  in  the 
current  MAPSKT  will  be  displayed  again,  and  the  user  will  be  again  asked  to  place  an  x  in 
front  of  imagery  groups  to  be  included  in  the  block.  This  gives  the  user  the  opportunity  to 
correct  mistakes  or  make  changes  in  the  choice  of  files  to  be  selected  in  a  block  without 
exiting  i.build.blk. 

Create  a  new  sub-block  within  the  block 

Ihe  following  menu  enables  the  user  to  create  a  sub-block  ait  of  a  single  imagery  group  in  the 
Hock.  Any  number  of  sub-blocks  may  be  created  by  repeating  the  option. 


LOCATION:  loration  MAPSET:  mapset 


BLOCK:  demo 

SUBBLOCK: _  (Mist’  will  show  available  sub-blocks) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  .,d>TO  CONTINUE 
(OR  <CtrI-C>TO  CANCEL) 


After  selecting  or  creating  a  sub-block,  this  menu  is  displayed: 


Mark  an  ’x’  by  only  one  imagery  group  to  form  sub-Mock  [75] 

x  groupl3  in  mapset 

_  groupl4  in  mapset 

_  group21  in  mapset 

_  group22  in  mapset 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


Ihe  user  is  then  given  the  opportunity  to  check  the  contents  of  the  sub-Mock: 


Subblock  [75]  references  the  following  raster  flic 


group!3  in  mapset 


Look  ok?  <yAi) 


If  the  user  responds  with  the  letter  n,  the  Mock  menu  will  appear  again  enaMing  the  user  to 
select  another  file  to  form  the  sub-Mock. 
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NOTES 

The  i. build.. blk  options  are  only  av  ailable  for  imagery  groups  in  the  current  LX  ICA'IION. 

The  ortho- rectification  programs  in  i.rectify.blk  currently  are  designed  as  single  photo  rectifications. 
Hence,  only  a  single  imagery'  group  may  be  selected  for  each  sub-block.  In  the  future  multi-photo 
rectification  may  become  available. 

This  program  remains  under  alpha  testing.  It  resides  in  the  src .alpha  directory  and  must  be  compiled 
separately  l tv  the  user. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 
i.group,  i.rnod.camera,  i.rectify.blk,  r.mapcalc 

AUTHOR 

Michael  Baba 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

i. camera  -  An  imagery  function  that  establishes  a  camera  reference  file  for  an  imagery  group,  and  runs 
interactively. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i. cam  era 

DESCRIPTION 

i.camera  selects  a  camera  reference  file  to  be  used  with  an  imagery  grcup.  In  the  imagery  programs 
i.ortho.reference ,  i.ortho.control,  and  i.ortho.rectify,  a  camera  reference  file  is  required  for 
computation  of  reference  points  and  ortho-rectification  parameters.  i.ca/nera  enables  the  user  to 
specify  an  existing  camera  reference  file  for  a  selected  imagery  group. 

i.camera  is  fully  interactive.  Ihe  program  first  prompts  the  user  for  the  name  of  the  imagery  group 
that  requires  a  camera  reference  file.  This  imagery  group  must  already  exist  under  the  user’s  current 
MAPSET  (see  i.group). 


The  program  next  asks  the  user  for  the  name  of  an  existing  camera  reference  file  to  be  used  with  the 
imagery  group  selected  above.  Ihe  GRASS  program  ijnod.camera  can  be  used  to  create  this  camera 
reference  file. 


NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  src .alpha  directory  and  must  be  compiled 
separately  by  the  user. 

FILES 

$GISE®ASE/SLOCAnON_NAME^MAPSET%roup 
SEE  ALSO 

i.group,  i.mod.camera,  i.ortho.control,  i. ortho. rectify,  i.ortho.reference 

AUTHOR 

Michael  Baba 
DBA  Systems,  Inc. 

10560  Arrowhead  Ekive 
Fairfax,  Virginia  22030 
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NAME 

i.cca  -  Canonical  components  analysis  (cca)  program  for  image  processing. 

(GRASS  Image  Processsing  Program) 

SYNOPSIS 

i.cca 

i.cca  help 

i.cca  group  =name  subgroup  =name  signature  -name  output  =name 
DESCRIPTION 

i.cca  is  an  image  processing  program  that  takes  from  two  to  eight  (raster)  band  files  and  a  signature 
file,  and  outputs  the  same  number  of  raster  band  files  transformed  to  provide  maximum  separability  of 
the  categories  indicated  by  the  signatures.  This  implementation  of  the  canonical  components 
transformation  is  based  on  the  algorithm  contained  in  the  I  .AS  image  processing  system. 


Typically  the  user  will  use  the  i.class  program  to  collect  a  set  of  signatures  and  then  pass  those 
signatures  along  with  the  raster  band  files  to  i.cca.  The  raster  band  file  names  are  specified  on  the 
command  line  by  giving  the  group  and  subgroup  that  were  used  to  collect  the  signatures. 


The  output  raster  map  names  are  built  by  appending  a  ".1",  ”.2”,  etc.  to  the  output  raster  map  name 
specified  on  the  command  line. 

Parameters: 


gcaap=name 
subgroup  =name 
signature  name 
output  name 


Name  of  the  imagery  group  to  which  the  2  to  8  raster  band  files  used  belong. 
Name  of  the  imagery  subgroup  to  which  the  2  to  8  raster  band  files  used  belong. 
Name  of  an  ASCU  file  containing  spectral  signatures. 

Output  raster  file  prefix  name.  The  output  raster  map  layer  names  are  built  by 
appending  a  “.1",  "2",  etc.  onto  the  output  name  specified  by  the  user. 


NOTES 

i.cca  respects  the  current  geographic  region  definition  and  the  current  mask  setting  while  performing 
the  transformation. 


SEE  ALSO 

Schowengerdt,  Robert  A.  Techniques  for  Image  Processing  and  Classification  in  Remote 
Sensing,  Academic  Press,  1983. 

i.class,  i.pca,  r.covar,  rjnapcalc 

AUTHORS 

Divid  Satnik,  GIS  laboratory.  Central  Washington  University 
Ali  R  Vali,  .Space  Research  Center,  University'  of  Texas,  Austin 
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NAME 

i. class  -  An  imagery  function  that  generates  spectral  signatures  for  an  image  by  allowing  the  user  to 
outline  regions  of  interest.  The  resulting  signature  file  can  be  used  as  input  for  ijnaxlik  or  as  a  seed 
signature  file  for  i, cluster. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i. class 

DESCRIPTION 

i. class  performs  the  fust  pass  in  the  GRASS  two- pass  supervised  image  classification  process;  the 
GRASS  prog  nun  i.maxlik  executes  the  second  pass.  Both  programs  must  be  run  to  generate  a 
classified  map  in  GRASS  raster  format. 

i. class  is  an  interactive  program  that  allows  the  user  to  outline  a  region  on  the  screen  and  calculate  the 
spectral  signature  based  on  the  cells  that  are  within  that  region.  During  this  process  the  user  will  be 
shown  a  histogram  of  the  region  for  each  image  band.  The  user  can  also  display  the  cells  of  the  image 
bands  which  fall  within  a  user-specified  number  of  standard  deviations  from  the  means  in  the  spectral 
signature.  By  doing  this,  the  user  can  see  how  much  erf  the  image  is  likely  to  be  put  into  the  class 
asstx  iated  with  the  current  signature. 

Ihe  spectral  signatures  that  result  are  composed  of  region  means  and  covariance  matrices.  These 
region  means  and  covariance  matrices  arc  used  in  the  second  pass  ( ijnaxlik )  to  classify  the  image. 

Alternatively ,  the  spectral  signatures  generated  by  i. class  can  be  used  for  seed  means  for  the  clusters  in 
the  i.cluster  program. 

USER  INPUTS 

The  first  screen  in  the  program  i. cl  ass  asks  the  user  for  the  imagery  group  and  subgroup  to  be 
analyzed: 


LOCATION:  location  SUPERVISED  CLASSIFIER  MAPSET:  demo 

Pleas*  select  the  group  and  subgroup  to  be  analyzed 

GROUP:  spot _  Gist  will  show  available  groups) 

SUBGROUP:  123 _  Qid  will  show  available  subgroups) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


The  group  should  contain  the  imagery  bands  that  the  user  wishes  to  classify.  The  subgroup  is  a  subset 
of  this  group.  The  user  must  create  a  group  and  a  subgroup  by  running  die  GRASS  program  i.group 
before  running  i. class.  The  subgroup  should  contain  only  the  image  bands  that  the  user  wishes  to 
classify.  Note  that  this  subgroup  must  contain  more  than  one  band. 

After  the  first  screen,  the  program  asks  the  user  for  the  name  of  the  resulting  signature  file.  The 
signature  file  is  both  the  output  file  for  i. class  and  the  required  input  file  for  the  GRASS  program 
i.maxlik.  It  contains  the  region  means  and  covariance  matrices  that  are  used  to  classify  an  image  in 
i.maxlik. 

After  entering  the  resulting  signature  file  name,  the  user  is  asked  to  enter  the  name  erf  a  seed  signature 
file.  This  is  optional.  A  "seed"  signature  file  is  a  previously  created  signature  file.  Such  a  seed 
signature  file  may  be  the  result  of  an  earlier  run  of  i.class.  The  seed  signature  file  is  copied  into  the 
new  resulting  signature  file  before  any  new  signatures  are  added  by  i.class.  In  this  way,  you  can 
collect  the  work  from  several  sessions  with  i.class  into  one  signature  file. 
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Next,  tlie  user  is  asked  to  enter  the  name  of  the  raster  map  to  be  displayed  during  the  process  of 
outlining  regions.  Typically,  the  user  will  want  to  enter  the  name  of  a  color  composite  previously 
created  by  i.composite.  However,  the  user  can  enter  the  name  of  any  existing  raster  map.  Ibis  leaves 
the  potential  for  using  a  raster  map  not  directly  derived  from  the  image  as  a  backdrop  on  which  the 
user  can  outline  the  classes  of  interest. 

At  this  point  the  i.class  graphics  screen  will  be  drawn  on  the  graphics  monitor  and  the  user  will  be 
directed  to  use  the  mouse.  From  this  point  on  the  user  will  primarily  work  with  the  mouse,  selecting 
options  from  the  menus  ;md  outlining  regions  on  the  screen.  The  only  time  that  the  user  w  ill  need  to 
return  to  the  text  terminal  is  to  enter  ruuncs  for  the  signatures  created. 

THE  DISPLAY  FRAMES 

The  display  frame  layout  that  i.class  uses  is  represented  below  for  reference. 


|  Menu  Frame  j 

+ . . . . . . + 

THE  MENUS 

All  of  the  menus  in  the  i.class  program  are  displayed  across  the  bottom  of  the  graphics  monitor  in  the 
Menu  Frame.  To  select  an  option  from  one  of  these  menus,  simply  place  the  cursor  over  your  selection 
and  press  any  button  on  the  mouse.  Inch  of  the  menus  is  discussed  in  the  follow  ing  paragraphs. 

The  Command  Menu 

The  Command  Menu  includes  the  following  selections: 

Zoom  -  This  command  allows  the  user  to  outline  a  recUmgular  region  in  cither  the  Map  or  Zoom 
Display  Frames  and  the  region  is  displayed,  magnified,  to  fit  in  the  Zoom  Display  Frame.  A  red 
rectangle  is  drawn  in  the  Map  Display  frame,  indicating  what  area  the  Zoom  Display  Frame  shows. 

To  outline  the  rectangular  region,  simply  use  any  mouse  button  to  anchor  the  first  comer  of  the  border 
and  then  use  any  Ixitton  to  chtx>se  the  other  comer. 

Define  region  -  This  selection  takes  the  user  to  the  Region  Menu.  This  menu  includes  the  options  that 
allow  the  user  to  outline  a  region  of  interest  on  the  displayed  raster  map. 

Redisplay  map  This  selection  takes  the  user  to  the  Redisplay  Menu.  The  Redisplay  Menu  allow  s  the 
user  to  redraw  map  display  fnunes. 


( iRASS  1.0  (Summer  l,|,,l ) 


l  .S.  Anm  (  I  Rl 


i  class 


( iRASS  Reference  M;uiual 


i. class 


Analyze  region  -  This  selection  starts  the  process  of  analyzing  the  currently  defined  region.  A 
liistogram  erf  the  defined  region  will  lx:  displayed  for  each  band.  On  the  histogram  for  each  band,  the 
mean,  standard  deviation,  minimum  cell  value  and  maximum  cell  value  are  marked.  The  histograms 
are  automatically  scaled  in  an  attempt  to  fit  the  data  into  the  space  available,  but  it  is  possible  that  all 
of  the  data  will  not  fit.  In  this  case,  as  much  of  the  data  as  possible,  centered  around  the  mean,  will  be 
displayed.  After  the  histograms  are  displayed,  the  user  will  be  given  the  Signature  Menu. 

Quit  -  The  user  should  make  this  selection  to  end  the  session  with  i.class. 

The  Region  Menn 

The  Region  Menu  contains  the  following  selections: 

Erase  region  -  This  selection  erases  any  currently  defined  region. 

Draw  region  -  This  selection  allows  the  user  to  use  the  n rouse  to  draw  a  region  on  either  the  Map  or 
Zoom  Display  Frame.  An  explanation  of  which  mouse  buttons  to  use  is  displayed  in  the  Menu  Frame. 
The  user  does  not  need  to  try  to  complete  the  region  boundary.  The  last  line  of  the  region  will  be 
added  when  the  user  selects  the  Complete  region  option  on  the  Region  Menu. 

Restore  last  region  -  This  selection  restores  the  last  region  that  was  drawn.  After  a  region  is 
completed,  it  will  be  saved  to  be  restored  later.  Only  one  previous  region  is  saved. 

Complete  region  -  This  selection  completes  the  region  that  is  currently  being  drawn.  As  noted  above, 
it  saves  the  complete  region  to  be  restored  later,  if  needed.  Once  the  user  has  made  a  complete  region, 
it  can  be  analyzed  with  the  Analyze  Region  selection  on  the  Command  Menu. 

Done  -  Use  this  selection  to  return  to  the  Command  Menu. 

The  Redisplay  Map  Menn 

The  Redisplay  Map  Menu  has  the  following  selections,  which  are  useful  to  redraw  the  raster  maps 
displayed  in  the  Map  and  Zoom  Display  Frames. 

Map  geographic  region  -  This  selection  causes  the  raster  map  in  the  Map  Display  Frame  to  be 
redrawn. 

Zoom  region  -  This  selection  causes  the  Zoom  Display  Frame  to  be  redrawn. 

Both  -  This  selection  causes  both  the  Map  and  Zoom  Display  Frames  to  be  redrawn. 

Cancel  -  Use  this  selection  if  you  do  not  want  to  redisplay  either  of  the  above  regions.  The  user  will 
be  returned  to  the  Command  Menu. 

The  Analyze  Region  Mean 

The  Analyze  Region  Menu  contaias  the  Signature  Menu,  which  allows  the  user  to  set  the  number  erf 
standard  deviations  and  the  display  color,  and  then  to  display  (as  an  overlay)  the  cells  that  match  the 
signature  within  the  number  of  standard  deviations  specified.  Note  that  once  the  matching  cells  are 
displayed,  the  Map  Display  Frame  must  be  redisplayed  to  see  only  the  original  raster  map  again.  The 
following  selections  are  available  on  the  Signature  Menu: 

Set  std  dev's  -  This  selection  allows  the  user  to  set  the  number  of  standard  deviations  from  the  mean 
for  the  maximum  and  minimum  range.  The  maximum  and  minimum  range  is  used  when  finding  the 
cells  that  "match"  the  signature.  The  user  is  presented  with  a  menu  of  typical  choices  and  an  "Other” 
option.  If  the  "Other''  option  is  selected,  enter  the  number  of  standard  deviations  from  the  keyboard  on 
the  text  terminal.  Otherwise,  the  selected  option  will  be  used.  When  the  number  of  standard  deviations 
is  set,  the  histograms  for  each  hand  will  be  redrawn  with  the  maximum  and  minimum  range  marked. 
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NoCe  that  the  number  in  parentheses  on  tliis  selection  is  the  current  number  of  standard  deviations. 

Set  color  -  This  selection  allows  the  user  to  set  the  color  for  the  display  of  cells  that  "match"  the 
current  signature.  The  user  is  presented  with  a  menu  of  color  choices.  Ihe  color  selected  will  be  used 
when  the  Display  Matches  Menu  selection  is  made. 

Note  that  the  color  in  parentheses  on  this  selection  is  the  current  color  for  display. 

Display  matches  -  Ibis  selection  displays  the  cells  that  "match"  the  current  signature  in  the  current 
color.  A  cell  "matches”  the  current  signature  if  the  cell  value  in  each  band  is  between  the  minimum 
range  and  maximum  range  for  that  band  defined  by  the  number  of  standard  deviations  currently  set. 

Done  -  What  this  selection  is  chosen,  the  user  will  be  asked  whether  or  not  he/she  would  like  to  save 
the  current  signature.  If  the  user  answers  with  the  "Yes"  selection,  he/she  will  be  asked  to  enter  a 
description  for  the  resultant  signature  file  on  the  text  terminal  keyboard.  The  saved  signature  file 
description  will  be  used  by  i.maxlik  to  name  the  category  that  is  created  from  the  current  signature. 
After  either  a  "No"  answer  or  the  signature  description  is  entered,  the  user  is  returned  to  tire  Command 
Menu. 

NOTES 

i.class  uses  the  current  MASK  to  generate  the  overlay  for  cells  that  match  a  signature.  As  a  result,  if  a 
MASK  already  exists  it  will  be  removed  during  the  execution  of  this  program. 

The  cell  values  in  the  image  bands  cannot  fall  out  si  vie  of  the  range  of  0  to  255.  i.class  will  report  an 
error  if  they  do. 

i.class ,  like  some  of  the  other  imagery  programs,  does  not  use  the  standard  GRASS  display  fr;ur»es. 
After  running  i.class,  you  will  need  to  create  a  display  frame  (eg.,  using  cLframe  or  d.erase)  Ivfore 
you  can  use  most  of  the  GRASS  display  (d.)  commands. 

i.group  must  be  run  Ixfore  i.class  to  create  an  imagery  group  and  a  sulrgroup  containing  the  image 
bands  to  be  classified. 

Ihe  user  can  perform  a  supervised  image  classification  by  running  i.class  followed  by  i.maxlik  The 
user  can  perform  an  unsupervised  classification  by  running  i.cluster  followed  (w  i.maxlik. 

i.class  is  interactive  and  requires  no  command  line  arguments.  Ihe  user  must  be  miming  a  graphics 
display  monitor  (see  d.mon)  to  run  this  program. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.frame,  d.mon,  g.region,  i.eca,  i.cluster,  i.eomposite,  i.group,  i.maxlik,  rjmpcalc,  r.mask 

AUTHOR 

David  Satnik,  Central  Washington  University  G1S  laboratory 
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NAME 

i. cluster  -  An  imagery  function  that  generates  spectral  signatures  for  land  cover  types  in  an  image 
using  a  clustering  algorithm.  The  resulting  signature  file  is  used  as  input  for  imaxlik,  to  generate  an 
unsupervised  image  classification. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.  cluster 

DESCRIPTION 

i.cluster  performs  the  first  pass  in  the  GRASS  two  pass  unsupervised  classification  of  imagery,  while 
the  GRASS  program  i.maxlik  executes  the  second  pass.  Both  programs  must  be  run  to  complete  the 
unsupervised  classification. 

i.cluster  is  a  clustering  algorithm  that  reads  through  the  (raster)  imagery  data  and  builds  pixel  clusters 
based  on  the  spectral  reflectances  of  the  pixels.  The  pixel  clusters  are  imagery  categories  t',al  can  be 
related  to  land  ewer  types  on  the  ground.  Ihe  spectral  distributions  erf  the  clusters  (which  will  be  the 
land  cover  spectral  signatures)  are  influenced  by  six  parameters  set  by  the  user.  Ihe  hrst  parameter  set 
by  the  user  is  the  initial  number  of  clusters  to  be  discriminated,  i.cl'ister  starts  by  generating  spectral 
signatures  for  this  number  of  clusters  and  "attempts"  to  end  up  with  this  number  of  clusters  during  the 
clustering  process.  Ihe  resulting  number  of  clusters  and  their  spectral  distributions,  however,  are  also 
influenced  by  the  range  of  the  spectral  values  (category  values)  in  the  image  files  and  the  other 
parameters  set  by'  ihe  user.  These  parameters  are:  die  minimum  cluster  size,  minimum  cluster 
separation,  the  percent  convergence,  the  maximum  number  of  iterations,  and  the  row  and  column 
sampling  intervals. 

The  cluster  spectral  signatures  that  re  ult  ct  composed  of  duster  means  and  covariance  matrices. 
These  cluster  means  and  cwariance  matrices  are  used  in  the  second  pass  ( imaxlik )  to  classify  the 
image.  The  clusters  or  spxtral  c’  \sses  that  result  can  be  related  to  land  cover  types  on  die  ground. 

USER  INPUTS 

Ihe  first  me..u  :n  the  prograi  i  i.cluster  asks  tl. ..  user  fur  the  imagery  group  and  subgroup  to  be 
analyzed: 


LOCATION:  location  CLUSTER  MAPSET:  demo 


Please  select  the  groupAubgroup  to  be  analyzed 


GROUP:  spot 

SUBGROUP:  123 _ 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


The  group  should  contain  the  imagery  files  that  the  user  wishes  to  classify.  The  subgroup  is  a  subset 
of  this  group.  The  user  must  create  a  group  and  subgroup  by  running  the  GRASS  program  i. group 
before  running  i.cluster.  The  subgroup  should  contain  only  the  imagery  band  files  that  the  user  wishes 
to  classify.  Note  that  this  subgroup  must  contain  more  than  one  band  file.  The  purpose  of  the  group 
and  subgroup  is  to  collect  map  layers  for  dassification  or  analysis. 

The  first  prompt  inside  the  program  asks  the  user  for  the  name  of  the  resulting  signature  file.  The 
signature  file  is  both  the  output  file  for  i.cluster  and  can  be  used  as  the  required  input  file  for  the 
(BLASS  program  i.maxlik.  It  contains  the  cluster  means  and  cwariance  matrices  that  are  used  to 
classify  an  image  in  i.maxlik  for  an  unsupervised  classification. 
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After  entering  the  signature  file  mime,  the  user  is  asked  to  enter  the  name  of  a  seed  signature  file.  This 
is  optional.  Seed  signatures  are  signatures  that  contain  cluster  means  and  covariance  matrices  that  were 
calculated  prior  to  the  current  run  erf  i.cluster.  They  may  be  acquired  from  a  previous  run  of  i.cluster 
or  from  a  supervised  classification  signature  training  site  selection  (eg.,  using  the  signature  file  output 
by  i.class).  The  purpose  of  seed  signatures  is  to  optimize  tire  cluster  decision  boundaries  (means)  for 
the  numlier  of  clusters  specified. 

The  final  menu  asks  the  user  for  the  clustering  parameters.  The  default  values  in  the  menu  are  the 
suggested  values  based  upon  the  total  number  of  rows  and  columns  in  the  image  files.  This  menu  also 
informs  the  user  of  the  number  of  rows  and  columns  of  the  image  files  that  are  included  in  the  current 
geographic  region.  Make  sure  that  this  geographic  region  is  large  enough  to  include  the  portion  of  the 
image  files  that  you  wish  to  classify. 


Please  set  the  fallowing  information 


Number  of  initial  classes  15 _ 

Minimum  class  size  17 _ 

Minimum  class  separation  0.50 

Percent  convergence  98.00. 


Maximum  number  of  iterations  30 _ 

Your  current  geographic  region  contains  100  rows  and  100  cols  (1000  cells) 

Please  set  the  sampling  intervals 

Row  interval  2 _ 

Col  interval  2 _ 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Orl-C>TO  CANCEL) 


Number  of  initial  classes 

This  is  the  number  of  clusters  that  will  initially  be  identified  in  the  clustering  process  before 
the  iterations  begin. 

Minirmm  class  size 

This  is  the  minimum  number  of  pixels  that  will  be  used  to  define  a  cluster,  and  is  therefore  the 
minimum  number  of  pixels  for  which  means  and  covariance  matrices  will  be  calculated. 

Minirmm  class  separation 

This  is  the  minimum  separation  below  which  clusters  will  be  meiged  in  the  iteration  process. 
This  is  an  image-specific  numlier  (a  "magic"  number)  that  depends  on  the  image  data  being 
classified  and  the  number  of  final  clusters  that  are  acceptable.  Its  determination  requires 
experimentation.  Note  that  as  the  minimum  class  (or  cluster)  separation  is  increased,  the 
maximum  number  of  iterations  should  also  lie  increased  to  achieve  this  separation  with  a  high 
percentage  of  convetgencc  (sec  percent  convergence). 

Percent  convergence 

A  high  percent  convergence  is  the  point  at  which  cluster  means  become  stable  during  the 
iteration  process.  When  clusters  are  being  created,  their  means  constantly  change  as  pixels  arc 
assigned  to  them  and  the  mean  is  recalculated  to  include  the  new  pixel.  After  all  clusters  have 
been  created,  i.cluster  begins  iterations  that  change  cluster  means  by  maximizing  the  distances 
between  them.  As  these  means  shift,  a  higher  and  higher  convergence  is  approached.  Because 
means  will  never  become  totally  static,  a  percent  convergence  and  a  maximum  number  of 
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iterations  is  supplied  to  stop  the  iterative  process.  The  percent  convergence  should  be  reached 
before  the  maximum  number  of  iterations.  If  the  maximum  number  of  iterations  is  reached,  it 
is  probable  that  the  desired  percent  convergence  was  not  reached.  The  number  of  iterations  is 
reported  in  the  cluster  statistics  in  mail  (see  NOTFS). 

Maxi  mint  number  of  iterations 

This  is  a  number  which  is  greater  than  the  number  of  iterations  predicted  to  achieve  the 
optimum  percent  convergence.  If  the  number  of  iterations  reaches  the  maximum  designated  by 
the  user,  the  user  may  want  to  rerun  i.cluster  with  a  higher  number  of  iterations  (see  NOTES). 

Raw  and  column  sampling  intervals 

These  numbers  are  based  on  the  size  of  the  data  set. 

NOTES 

i.cluster  will  run  in  the  background  and  notify  the  user  by  mail  when  it  is  complete.  The  mail 
message  will  contain  the  results,  i.e.,  the  statistics  for  each  cluster.  Also  included  in  the  mail  message 
are  the  resulting  percent  convergence  for  the  clusters,  the  number  of  iterations  that  were  required  to 
achieve  the  convergence,  and  the  separability  matrix . 

i.group  must  be  run  before  i.cluster  to  create  an  imagery  group  and  a  subgroup  containing  the  image 
band  files  to  be  classified. 

'Ibis  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 
i.class,  i.group,  ijnaxlik 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i. colors  -  An  imagery  function  that  creates  colors  for  imagery  groups. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.colors 

DESCRIPTION 

i.colors  allows  the  user  to  interactively  assign  red,  green,  and  blue  colors  to  the  band  files  in  an 
imagery  group  while  viewing  the  display  of  the  combined  bands  on  the  graphics  monitor. 

The  user  is  asked  to  select  an  imagery  group.  Band  files  in  the  group  that  are  currently  assigned  to  the 
red,  green,  and  blue  color  bands  are  display  ed  along  the  left  edge  of  the  user’s  graphics  display  frame, 
and  a  composite  image  of  these  bands  is  displayed  in  the  right  portion  of  the  display  frame.  A  small 
matrix  appears  in  the  lower  left  portion  of  the  display  frame,  and  reflects  current  red.  green,  and  blue 
band  file  color  assignments.  Red,  green,  and  blue  color  boxes  appear  next  to  the  names  of  the  image 
band  files  to  which  they  are  currently  assigned.  The  user  can  change  current  color  assignments  by 
clicking  the  mouse  cursor  beside  desired  color  assignments. 

A  menu  along  the  bottom  of  the  graphics  display  frame  indicates  that  the  user  can  also  replot  ;uid 
ertlaige  the  composite  image  on  display,  or  quit  the  program,  by  clicking  the  mouse  cursor  on  the 
desired  option. 

The  GRASS  program  i.group  can  also  be  used  to  assign  red,  green,  and  blue  colors  to  imagery  gnxip 
band  files. 

NOTES 

This  program  is  not  yet  complete.  To  assign  colors  to  an  imagery  group,  ilsc  the  GRASS  program 
i.group. 

Iliis  program  is  interactive  and  requires  no  command  line  arguments.  Ihe  user  must  lx*  running  a 
graphics  monitor  to  use  this  program. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.mon,  hsv.rgb.sh,  i.eomposile,  i.grey. scale,  i.group,  i.his.rgb,  i.rgb.his,  rjnapcalc.  rgb.hsv.sh 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Ihginecring  Research  lalxrratory 
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NAME 

i. composite  -  An  imagery  function  that  creates  a  color  composite  image  from  three  imagery  band  files 
specified  by  the  user. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.composite 

DKSCRIPTION 

i.composite  creates  a  color  composite  image  from  three  band  files  specified  by  the  user.  The  user 
specifies  the  bands  to  be  used  by  assigning  a  red,  blue,  and/or  green  color  to  each  band.  The  resulting 
image  is  a  raster  map  layer  of  raw  spectral  data  composed  of  the  three  bands  chosen  by  the  user.  The 
color  composite  can  then  be  displayed,  painted,  or  manipulated  as  would  anv  raster  map  layer  in 
CiRASS. 

lhe  first  prompt  asks  the  user  for  the  imagery  group  whose  files  are  to  be  used. 

Ihe  following  menu  is  then  displayed: 


Please  indicate  which  files  to  use  for  red,  green,  and  blue  colors.  Yon  may  leave  any  color 
out.  You  may  specify  more  than  one  color  per  file.  However,  each  color  may  only  be 
specified  once.  For  example,  to  get  a  foil  color  image,  specify  r^Jb  for  3  different  files.  To 
get  a  grey  scale  image,  specify  rgb  for  a  single  file. 


b _ 

gpot.l 

8 — 

spot  22 

r _ 

spot  J 

— 

spot  cl  ass 

_ 

spotreject 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


Ihe  user  is  then  allowed  to  check  the  choice  erf  bands: 


Colors  assigned  as  follows: 

RED:  spot3@mapsetname 

GREEN:  spat.2@mapsetnaine 

BLUE:  spot.l@mapsetname 

Look  ok?  (y/h)  [y] 


Ihe  color  talrfe  that  is  created  has  1000  colors  (10  saturation  levels  (or  sltades)  |x:r  primary  color  (blue, 
green,  red)).  The  number  of  colors  that  can  be  displayed  at  one  time  on  a  ''dor  graphics  nxniitor  will 
depend  on  the  graphics  monitor  being  used.  For  example,  if  tire  graphics  monitor  can  only  cb  splay  512 
colors  at  one  lime,  then  the  user  must  nm  tlx;  GRASS  command  d.colormodc  mode  -fixed  before 
displaying  the  raster  map  layer,  lhe  cdors  that  cannot  lx-  displayed  will  be  assigned  tv)  the  nearest 
displayable  cdor,  and  the  raster  map  layer  will  retain  its  relative  color  accuracy  If  the  user  is  in  float 
colormodc,  however,  the  raster  map  layer  displayed  on  the  graphics  monitor  will  not  accurately  reflect 
ihe  map’s  real  color  assignments. 
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The  user  is  then  asked  to  name  the  composite  image  raster  map  layer.  The  percentage  completed  is 
echoed  to  the  screen  and  r support  files  are  created  automatically. 

NOTES 

The  user  should  always  check  the  geographic  region  settings  before  naming  most  imagery  commands. 
It  is  vety  easy  for  the  boundaries  of  the  geographic  region  to  be  completely  off  the  image.  Before 
running  i. composite,  or  other  imagery  commands,  the  user  should  probably  set  the  geographic  region  to 
match  that  of  the  raster  map  layers  to  be  read.  This  can  be  accomplished  using  option  4  of  the 
g.region  command. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.colormode,  d.his,  d.rast,  g.region,  ixoiors,  i. grey  scale,  i.group,  r  support 

AUTHOR 

Michael  Shapiro,  U.S.  Anny  Construction  Engineering  Research  Laboratory 
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NAME 

i.fft  -  Fast  Fourier  Transform  (FF'I)  for  image  processing. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

iJft 

lift  help 

i-fft  input_image=/iome  real  image  name  imaginary  image  name  [ range  rvalue] 
DESCRIPTION 

i.fft  is  an  image  processing  program  based  on  the  algorithm  given  by  Press  (1988),  with  enhancements 
by  Vali  (1990),  thiit  processes  a  single  input  raster  map  layer  (input  Jmage)  and  constructs  the  real  and 
imaginary  Fourier  components  in  frequency  space. 

Parameters: 

input  image  =name  Input  raster  map  layer  on  which  the  fast  Fourier  transform  is  run. 

real  image  name  Output  real  part  arrays  stored  as  raster  map  layer, 

imaginary  image  name  Output  imaginary’  part  arrays  stored  as  raster  map  layer, 
range  value  Range  of  values  used  during  fast  Fourier  transformation. 

The  real  and  imaginary  components  are  stored  as  arrays  of  doubles  in  the  cclLjnisc  directory  (for  use 
in  the  inverse  transform  program,  i.ifft),  and  are  also  scaled  and  formatted  into  the  real_image  and 
imaginary  Jmage  raster  map  layers  for  inspection,  masking,  etc.  In  these  raster  map  layers  the  low 
frequency  components  are  in  the  center  and  the  high  frequency  components  are  toward  the  edges.  The 
input  Jmage  need  not  lie  square;  before  processing,  the  X  and  Y  dimensions  of  the  input  Jmage  are 
padded  with  zeroes  to  the  next  highest  power  of  two  in  extent  (i.c.,  256  x  256  is  processed  at  that  size, 
but  200  x  400  is  padded  to  256  x  512).  The  cell  category  values  for  viewing,  etc.,  are  calculated  by 
taking  the  natural  log  of  the  actual  values  then  rescaling  to  255,  or  whatever  optional  range  is  given  on 
the  command  line,  as  suggested  by  Richards  (1986).  A  color  table  is  assigned  to  the  resultant  map 
layer. 

The  current  geographic  region  and  mask  settings  are  respected  when  reading  the  input  file.  The 
presence  of  a  mask  will,  in  general,  make  the  resulting  fast  Fourier  transform  invalid,  or  at  least 
difficult  to  interpret. 

SEE  ALSO 

Numerical  Recipes  in  C,  by  William  II  Press.  Cambridge  University  Press,  1988. 

Remote  Sensing  Digital  Image  Analysis,  by  John  A  Richards,  Springer- Verlag,  1986. 

Persomud  communication,  between  progam  author  and  Ali  R.  Vali,  Space  Research  Center,  University 
of  Texas,  Austin,  1990. 

i.cca,  i. class,  ijfjt,  i.pca 

AUTHOR 

Dtivid  Satnik,  GIS  UiUxatory,  Central  Washington  University 
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NAME 

i.greyjcale  -  An  interactive  imagery  function  that  assigns  a  histogram  contrast  stretch  grey  scale  color 
table  to  a  raster  map  layer. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.greyjcale 

DESCRIPTION 

i.greyjcale  is  an  interactive  imagery  function  that  assigns  a  histogram  contrast  stretch  grey  scale  col  ea¬ 
table  to  a  raster  map  layer.  The  histogram  contrast  stretch  expands  the  original  range  of  digital 
(category)  values  to  utilize  the  full  range  of  the  user’s  graphics  monitor. 

The  user  is  asked  for  the  name  of  the  raster  map  layer  that  needs  a  grey  scale.  When  the  raster  map 
layer  is  displayed,  it  will  be  displayed  with  a  grey  scale  color  scheme. 

NOTES 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

dxolormode,  dxolors,  dxoiortable,  i.colors,  ixomposite 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i.group  -  An  imagery  function  that  creates  and  edits  groups  and  subgroups  of  (raster)  imagery  files. 
(GRASS  Image  Processing  Program) 

SYNOPSIS 

i-group 

DESCRIPTION 

i.group  allows  the  user  to  collect  raster  map  layers  in  an  imagery  group  by  assigning  them  to  user- 
named  subgroups  or  other  groups.  Ibis  enables  the  user  to  run  analyses  on  any  combination  of  the 
raster  map  layers  in  a  group.  The  user  creates  the  groups  and  subgroups  and  selects  the  raster  map 
layers  that  are  to  reside  in  them.  Imagery'  analysis  programs  like  i.points,  i. rectify,  i.ortho.rectify  and 
others  ask  the  user  for  the  name  of  an  imagery  group  whose  data  are  to  be  analyzed.  Imagery  analysis 
programs  like  i. cluster  and  i.maxlik  ask  the  user  for  the  imagery  group  and  imagery  subgroup  whose 
data  are  to  lie  analyzed. 

The  first  menu  in  the  i.group  program  asks  the  user  to  select  a  group.  If  the  group  does  not  exist,  the 
user  will  be  asked  if  he  or  she  would  like  to  create  a  new  group. 


This  program  edits  imagery  groups.  You  may  add  raster  map  layers  to,  or  remove  such 
layers  from,  an  imagery  group.  You  may  also  create  new  groups. 

Please  enter  the  group  to  be  createdAnodified 

CROUP: _  (enter  ’list’  for  a  list  of  groups) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 

(OR  <Ctrl-C>TO  EXIT) 


If  the  word  list  is  entered,  groups  that  have  alreath  been  created  in  the  user’s  current 
IjOCAT!QN_NAME  and  MAPSET(S)  will  be  listed.  Tlie  second  menu  in  i.group  provides  the  user 
with  the  following  options: 


1.  Select  a  different  group 

2.  Edit  group  title 

3.  Include  new  raster  (cell)  files  in  the  group 
or  remove  raster  (cell)  files  from  the  group 

4.  Assign  colors  to  the  group 

5.  Create  a  new  subgroup  within  the  group 

RETURN  to  exit 


GRASS  4.0  (Summer  I  VO  I ) 


U.S.  Army  CERL 


131 


i. group 


GRASS  Reference  Manual 


i -group 


The  options  are  described  as  follows: 

Select  a  different  group 

If  option  number  1  is  chosen,  the  following  menu  is  displayed: 


Please  enter  the  group  to  be  createdAnod  ird 
GROUP: _ _  (enter  ’list’  for  a  list  of  groups) 

AFTER  COMPLETING  ALL  ANSWERS,  U1T  <ESOTO  CONTINUE 

(OR  <Ctrl-C>TO  EXIT) 


If  the  word  list  is  entered,  groups  that  have  already  been  created  in  the  current 
I/X:ATION_NAMi:  and  MAPSIT(S)  will  be  displayed. 

Edit  group  title 

If  option  number  2  is  selected,  an  entry  space  is  provided  to  type  in  the  group  title.  This  title 
is  useful  in  identifying  each  group: 


TITLE 


This  option  offers  an  opportunity  to  go  hack  aixl  change  the  entrv  if  it  is  not  correct  by  asking: 

Look  ok?  (yAi). 

Include  new  raster  < cell )  files  in  the  group  or  remove  raster  (cell)  files  from  the  group 
When  choosing  option  number  3,  the  following  menu  is  displayed: 

LOCATION:  location  GROUP:  spot  MAPSET:  demo 

If  you  wish  to  delete  a  tile  from  group  [ spot],  remove  the  ’i’  from  in  front  of  the 
file  name. 

x_  spot. I  in  demo 

x_  spot .2  in  demo 

x_  spot 3  in  demo 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  Ctrl-C>TO  CANCEL) 


GRASS  4.0  i  Summer  I I  i 


1  S.  Armv  (  I  RI 


132 


i. group 


GRASS  Reference  Manual 


» -group 


Next,  a  menu  listing  all  the  other  raster  map  layers  present  in  the  current  MAPSEIXS)  will  be 
displayed: 


LOCATION:  location  GROUP:  spot  MAPSET:  demo 
Please  mark  an  ’x*  by  the  files  to  be  added  in  group  [spot] 
MAPSET:  demo 

x_  composite  1 
x  spot  d  ass  1 

spotdass2 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  Ctrl-C>TO  CANCEL) 


If  more  than  one  MAPSEI'  is  selected,  menus  for  those  mapsets  will  also  be  dismayed.  All 
raster  map  layers  selected  with  an  ’x’  will  be  included  in  the  group  being  updated. 

The  user  will  then  have  the  opportunity  to  check  the  contents  of  the  group  that  was  just 
modified: 

Group  [spot]  references  the  following  raster  files 


spot.l  in  demo 

spot  .2  in  demo 

spot  3  in  demo 

composite!  in  demo 

spotclassl  in  demo 


Look  ok?  (yAi) 


If  the  user  responds  with  tlic  letter  y,  then  the  following  sentence  is  displayed  on  the  screen: 


Group  [spot]  updated! 


Aiul  the  main  menu  for  i. group  returns. 

If  the  user  responds  n,  the  menu  containing  the  group  files  after  it  was  modified  will  be 
displayed  and  the  user  will  be  asked  to  place  an  x  in  faint  of  those  raster  map  layers  that  are 
to  lie  removed  front  the  group.  Then,  a  menu  listing  all  of  the  other  raster  map  layers  in  the 
current  MAPSIT  will  lie  displayed  again,  anil  the  user  will  be  again  asked  to  place  an  x  in 
front  of  raster  map  layers  to  be  included  in  the  group.  This  gives  the  user  the  opportunity  to 
correct  mistakes  or  make  changes  in  the  clioicc  of  raster  map  layers  to  lie  selected  in  a  group 
without  exiting  i.group. 
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Assign  colors  to  the  group 

Option  number  4  provides  the  following  menu: 


Please  indicate  which  files  to  use  for  red,  green,  and  blue  colors.  You  may  leave 
any  color  out.  You  may  specify  more  than  one  color  per  file.  However,  each  color 
may  only  be  specified  once.  For  example,  to  get  a  foil  color  image,  specify  r,g,b  for 
3  different  files.  To  get  a  grey  scale  image,  specify  rgb  for  a  single  file. 


b _ 

spot.l 

g — 

spot  .2 

r _ 

spot  .3 

_ 

composite  1 

-- 

spot  class! 

«<r^Jb  can  only  be  specified  once  »> 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  <Ctri-C>TO  CANCEL) 


This  menu  allows  you  to  select  a  color  for  each  imagery  band  or  for  each  file  for  display. 
Note,  however,  that  composite  images  and  classified  images  are  already  assigned  colors  during 
their  creation. 

An  opportunity  to  change  the  choice  of  colors  is  offered  after  escaping  the  menu  by: 

Look  ok?  (y/h) 


Create  a  new  subgroup  within  the  group 

The  folk  wing  menu  enables  the  user  to  create  a  subgroup  out  of  any  combination  of  raster 
map  layers  in  the  gr<xtp.  Any  number  of  subgroups  may  lx:  created  by  repeating  tlx:  option. 


LOCATION:  location  MAPSET:  spot 


GROUP:  spoil 

SUBGROUP: _ Clist’  will  show  available  subgroups) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


After  selecting  or  creating  a  suligroup,  this  menu  is  displayed: 
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Mark  an  ’x’  by  the  files  to  form  subgroup  [123\ 

*_  spot.l 
3L_  spot  .2 
x^_  spotj 

_  composite  i 

_  spot  cl  ass  1 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


The  user  is  then  given  the  opportunity  to  check  the  contents  of  the  subgroup: 


Subgroup  [123]  references  the  following  raster  (ceil)  files 


spot.l 

in  demo 

spot  .2 

in  demo 

spot  J 

in  demo 

Look  ok?  (yAi) 


If  the  user  responds  with  the  letter  n,  the  group  menu  will  appear  again  enabling  the  user  to 
select  raster  map  layers  to  form  the  subgroup. 


NOTES 

The  i. group  options  are  only  available  for  imagery  map  layers  in  the  current  LOCATION_NAK*E. 
Subgroup  names  may  not  contain  more  than  12  characters. 

Ihis  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 
i. cluster,  ijnaxlik,  i.points,  i.rectify 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Constniction  Engineering  Rese;trch  laboratory 


ro 


GRASS  4.0  (Summer  1W1) 


U.S.  Ami'  t'ERl. 


i.his.igb 


GRASS  Reference  Manual 


i.his.rgb 


NAME 

i.his.rgb  -  Hie-intensity-saturation  (his)  to  red-green-blue  (rgb)  raster  map  color  transformation 
function. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

iJli&xgb 
i.hi&xgb  help 

iJusjrgb  hue  input  =name  intensity .input  =name  saturation.input  =name 
red  output  name  greenoutput  name  blue  output  nartu’ 

DESCRIPTION 

i.his.rgb  is  an  image  processing  program  that  processes  three  input  raster  map  layers  as  hue,  intensity 
and  saturation  components  and  produces  three  output  raster  map  layers  representing  the  red,  green  and 
blue  components  of  this  data.  Ihe  output  raster  map  layers  are  created  by  a  standard  hue-intensity - 
saturation  (his)  to  red  grecirblue  (rgb)  color  transformation.  Each  output  raster  map  layer  is  given  a 
linear  gray  scale  color  table.  The  current  geographic  region  and  mask  settings  are  respected. 

Parameters: 
hueinput  —name 
intensity  .input  name 
satur  ationinput  =name 
red  output  name 
green  output  name 
blueoutp  .ame 

NOTES 

It  is  not  possible  to  process  three  bands  with  i.his.rgb  and  then  exactly  recov  er  the  original  bands  with 
i.rgb.his.  litis  is  due  to  loss  of  precision  because  ol  integer  computations  and  rounding.  Tests  have 
shown  that  more  titan  70%  of  the  original  cell  v;dues  will  lx-  reproduced  exactlv  after  transformation  in 
lx>th  directions  and  that  09%  will  lx:  within  j>lus  or  minus  1.  A  few  cell  values  may  dillcr  signilicanily 
front  their  original  values. 

SEE  ALSO 

hsv.rgb.sh,  :  ~'>lors,  i.grey. scale,  i.rgb.his.  rgb.hsv.sh 

AUTHORS 

Thviti  Satnik,  GIS  laboratory,  Central  Washington  University 

with  acknowledgements  to  Ali  Vali,  Univ.  of  Texas  Space  Rcscttrch  (  enter,  for  the  core  routine. 


Name  of  input  raster  map  layer  representing  hue. 

Name  of  input  raster  map  layer  representing  intensity. 

Name  of  input  raster  nuip  layer  representing  saturation. 

Output  raster  map  layer  representing  the  red  component  in  the  data. 
Outjxit  raster  map  layer  representing  the  green  component  in  tin-  data. 
Output  raster  map  layer  representing  the  blue  coni]v>nent  in  the  data. 
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NAME 

i.ifft  -  Inverse  Fast  Fourier  Transform  (ifft)  for  image  processing. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.ifft 

i.ifft  help 

i.ifft  real  image  name  imaginary  image  name  outputimage  =name 
DESCRIPTION 

i.ifft  is  an  image  processing  program  based  on  the  algorithm  given  by  Press  (1988),  and  modified  by 
Vali  (1990),  that  converts  real  and  imaginary  frequency  space  images  (produced  by  i.fft )  into  a  normal 
image. 

Parameters: 

rea]_image=no/ne  Input  raster  map  layer  for  inversion  fast  Fourier  transform,  real  part, 

iniaginary  image  name  Input  raster  map  layer  for  inversion  fast  Fourier  transform,  imaginary 
(Nit put  image— szo/ne  Output  inversion  raster  map  layer  after  fast  Fourier  transformation. 

The  current  mask  is  respected  when  reading  the  real  and  imaginary  component  files;  thus,  r.mask 
become  a  primary  program  for  selecting  the  portion  of  the  frequency  space  data  to  be  included  in  the 
inv  erse  transform.  The  GRASS  program  dLdigit  can  be  used  to  create  masks  while  viewing  the  real  or 
imaginary  component  image.  When  i.ifft  is  executed,  it  (automatically)  uses  the  same  GRASS  region 
definition  setting  that  was  used  during  the  original  transformation  done  with  i.fft. 

The  real  and  imaginary  components  are  read  from  arrays  erf  doubles  in  the  cell^rmsc  directory 
(produced  by  the  forward  transform  program,  i.fft),  and  the  reconstructed  image  will  preserve  the  cell 
value  scaling  of  the  original  image  processed  by  i.fft.  No  color  table  is  assigned  to  the  output  map; 
one  should  be  created  before  viewing  the  output  mintage. 

SEE  ALSO 

Numerical  Recipes  in  C,  by  William  H.  Press,  Cambridge  Lkiiversity  Press,  1988. 

Remote  Sensing  Digital  Image  Analysis,  by  John  A  Richards,  Springer- Verlag,  1986. 

Personal  communication,  between  program  author  and  Ali  R.  Vali,  Space  Research  Center,  University 
of  Texas,  Austin,  1990. 

i.c.ca,  i.class,  i.fft,  i.pca 

AUTHOR 

David  Satnik.  GIS  laboratory,  Central  Washington  University 
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NAME 

i.maxlik  -  An  imagery  function  that  classifies  the  cell  spectral  reflectances  in  imagery  data  based  on  the 
spectral  signature  information  generated  by  either  i.cluster  or  i. class. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

ijnaxlik 

DESCRIPTION 

i.maxlik  is  a  maximum-likelihood  discriminant  analysis  classifier.  It  can  be  used  to  perform  the  second 
step  in  either  an  unsupervised  or  a  supervised  image  classification. 

Both  image  classification  methods  are  performed  in  two  steps.  The  first  step  in  an  unsupervised  image 
classification  is  performed  by  i.cluster,  while  the  first  step  in  a  supervised  classification  is  executed  by 
the  GRASS  program  i.class.  In  both  cases,  the  second  step  in  the  image  classification  procedure  is 
performed  by  i.maxlik. 

In  an  unsupervised  classification,  the  maximum-likelihood  classifier  uses  the  cluster  means  and 
covariance  matrices  from  the  i.cluster  signature  file  to  determine  to  which  category  (spectral  class) 
each  cell  in  the  image  has  the  highest  probability  of  belonging.  In  a  supervised  image  classification, 
the  maximum-likelihood  classifier  uses  the  region  means  and  covariance  matrices  from  the  spectral 
signature  file  generated  by  i.class,  based  on  regions  (groups  of  image  pixels)  chosen  by  the  user,  to 
determine  to  which  category  each  cell  in  the  image  has  the  highest  probability  of  belonging. 

In  either  case,  the  raster  map  layer  output  by  ijnaxlik  is  a  classified  image  in  which  each  cell  has  been 
assigned  to  a  spectral  class  (i.e.,  a  category).  The  spectral  classes  (categories)  can  lie  related  to  specific 
land  cover  types  on  the  ground. 

The  first  screen  asks  the  user  for  the  group  and  subgroup  to  be  classified: 


Please  select  the  group/subgroup  containing  the  signatures 
to  be  used  in  the  classification 


CROUP:  spot 

SUBGROUP:  123. 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


This  group  should  contain  the  subgroup  to  be  classified.  Ihe  subgroup  should  contain  the  band  files 
that  were  used  to  create  the  signature  tile  in  the  prograin  i.cluster  or  i.class. 

llic  user  is  tlien  prompted  for  the  name  of  the  signature  file  to  lx-  used  for  the  classification.  Ihc 
.signature  file  contains  the  cluster  and  covariance  matrices  tliat  were  calculated  by  the  GRASS  program 
i.cluster  (or  the  region  means  and  covariance  matrices  generated  by  i.class.  if  the  user  runs  a 
sujxrvised  classification).  Ihcse  spectral  signatures  are  what  determine  the  categories  (classes)  to 
which  image  pixels  will  lx  assigned  during  the  classification  process. 

'Ihc  next  prompt  asks  the  user  to  assign  a  name  to  the  classified  raster  map  layer  that  w  ill  lx  generated 
In  i.maxlik.  This  new  raster  map  layer  will  contain  categories  that  c;ui  be  related  to  land  cover 
categories  on  the  ground. 
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Next,  the  user  is  asked  to  assign  a  name  to  the  reject  threshold  raster  map  layer  that  is  also  generated 
by  i.maxlik.  After  classifying  the  image,  ijnaxlik  runs  a  chi  square  test  on  each  discriminant  result  at 
various  threshold  levels  of  confidence  to  determine  the  confidence  level  associated  with  each  cell  class 
(category).  This  is  the  reject  threshold  map  layer.  It  contains  one  calculated  confidence  level  for  each 
classified  cell  in  the  classified  image.  One  of  the  possible  uses  for  this  map  layer  is  as  a  mask,  to 
identify  cells  in  the  classified  image  that  have  the  lowest  probability  of  being  assigned  to  the  connect 
class. 

Next,  the  following  menu  is  displayed: 


COLOR  CONFIGURATION  FOR  CLASSIFIED  LAYER  [ spotclassl ] 


Please  indicate  which  raster  map  layers  to  use  for  red,  green,  and  blue  colors.  Yon  may 
leave  any  color  out.  Yon  may  specify  more  than  one  color  per  color  file.  However,  each 
color  may  only  be  used  once. 

For  example,  to  get  a  fall  color  image,  specify  rgl>  for  3  different  files.  To  get  a  grey 
scale  image,  specify  rgb  for  a  single  file. 


b. 


r. 


spot.l  in  demo 
spot .2  in  demo 
spot .3  in  demo 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  Ctrl -C>  TO  CANCEL) 


More  than  three  bands  (raster  map  layers)  can  be  classified,  but  since  only  three  bands  can  be  displayed 
at  most  color  graphics  monitors  at  one  time,  only  three  bands  are  assigned  a  color  in  the  above  menu. 
This  subgroup,  therefore,  could  liavc  more  than  three  bands  in  it. 

i.maxlik  runs  in  the  background  aixl  the  user  is  notified  by  mail  when  it  is  complete. 

NOTES 

Hie  maximum-likeli  hood  classifier  assumes  that  the  spectral  signatures  for  each  class  (category)  in  each 
band  file  are  normally  distributed  (i.c.,  Gaussian  in  nature).  Gustering  algorithms,  however,  can  create 
signatures  that  are  not  normally  distributed.  If  this  occurs,  ijnaxlik  will  reject  them  and  display  an 
error  message. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

Grass  Tutorial:  Image  Processing 
i.class,  i.cluster,  i.group,  rjnask 

AUTHOR 

Michael  Shapiro,  U.S.  Army  (jonstniction  Engineering  Research  Laboratory 
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NAME 

i.median  -  An  interactive  imagery  function  that  creates  a  raster  map  layer  whose  color  table  is  based 
on  the  red,  green,  and  blue  color  values  present  in  existing,  user- specified  imagery  group  files. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i  .median 

DESCRIPTION 

i.median  is  an  interactive  imagery  function  that  allows  the  user  to  create  a  new  raster  map  layer  whose 
color  table  values  are  based  on  the  red,  green,  and  blue  color  values  present  in  (as  many  as)  three  raster 
map  layers  in  an  imagery  group. 

The  user  is  first  asked  to  enter  the  name  of  the  imagery  group  from  whose  map  layers  red,  green,  and 
Hue  color  values  are  to  be  extracted.  The  user  is  then  shown  a  listing  of  imagery  files  in  the  specified 
group,  and  is  asked  to  indicate  which  files  in  the  group  are  to  be  used  for  red,  green,  and  blue  colors  in 
the  new  map  layer.  Each  color  (red,  green,  and  blue)  must  be  specified  once  and  only  once. 

The  user  is  also  asked  to  assign  a  name  to  the  new  raster  map  layer  output. 

NOTES 

This  program  is  interactive  and  reqitires  no  command  line  arguments. 

The  input  files  must  ALL  be  within  the  range  of  0-255. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

Paul  Heckbert,  "Image  Quantization,"  Siggraph  Proceedings  1982 

d-colormode,  d.colors,  d.colortable,  hsv.rgb.sh,  i.colors,  i.eomposite,  i-grey. scale,  i.group, 
i.his.rgb,  i.rgb.his,  r.mapcalc,  rgb.hsb.sh,  r. colors 

AUTHOR 

David  Gerdes,  U.S.  Army  (xmstruction  Engineering  Research  Laboratory 
Reference  Paul  I  fcekbert,  "Image  Quantization,"  Siggraph  Proceedings  1982 
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NAMK 

i.mod.catntra  -  An  imagery  function  that  creates  or  modifies  entries  in  a  camera  reference  file. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i  .mod  .earner  a 
i. mod  .camera  help 

DESCRIPTION 

i.mod.camera  creates  or  modifies  entries  in  a  camera  reference  file.  In  the  imagery  programs 
i.ortho.reference,  i.ortho.control,  and  i.ortho.reclify,  a  camera  reference  file  is  required  for 
computation  of  reference  points  and  ortho-rectification  parameters.  The  program  i. earner  a,  which 
selects  a  camera  reference  file  to  he  used  with  an  imagery  group,  also  requires  an  existing  camera 
reference  file. 

This  program  runs  interactively.  It  first  prompts  the  user  for  the  name  of  the  camera  reference  file  to 
be  created  or  modified. 

The  follow  iii;  maiu  is  then  displayed; 

Please  provide  the  following  information 

Camera  Name:  camera  name _ 

Camera  Identification:  identification 

Calibrated  Focal  Length  mm.:  _ 

Point  of  Symmetry:  X-coordinate  mm.:  _ 

Point  of  Symmetry:  Y-coordinate  mm.:  _ 

Maximum  number  of  fiducial  or  reseau  marks: _ 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


The  user  is  then  asked  to  enter  the  X  and  Y  photo  coordinates  of  each  fiducial  as  follows: 
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Please  provide  the  following  information 


Fid#  Fid  ID 

Xf 

Yf 

1 

0.0 

0.0 

2 

0.0 

0.0 

3 

0.0 

0.0 

4 

0.0 

0.0 

5 

0.0 

0.0 

6 

0.0 

0.0 

7 

0.0 

0.0 

H 

0.0 

0.0 

9 

0.0 

0.0 

10 

0.0 _ 

0.0 _ 

next:  end _ 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>  TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 

The  input  display  is  repeated  until  the  maximum  number  of  fiducials  specified  by  the  user  is  reached. 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  src.alpha  directory  and  must  be  compiled 
separately  by'  the  user. 

FILES 

Camera  reference  files  are  stored  under  the  directors' 

SGISDBASE/SI X XJATIOK  NAMF/SMARSET/caniera.  (This  is  the  same  as  SIXlCATTON/camera,  the 
/camera  directory  luider  the  user’s  current  mapset.) 

SEE  ALSO 

i.camera,  i.ortho.conlrol,  i.ortho.rectify,  i.orlho.referenc.e 

AUTHOR 

Michael  Baba 
ESA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

i.pea  -  Principal  components  analysis  (pea)  program  for  image  processing. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.pea 

i.pea  help 

i.pea  inputl  =name  input2  =name  [inpuLC  name]  [input4=name]  [input5=/m/nc] 

[input 6 ^name \  (input7  name]  [ input8  -name]  output  name 

DESCRIPTION 

i.pea  is  an  image  processing  program  based  on  the  algorithm  provided  by  Vali  (1990),  that  processes  n 
(2  <=  n  <=  8)  input  raster  map  layers  and  produces  n  output  raster  map  layers  containing  the  principal 
components  of  the  input  data  in  decreasing  order  of  variance  ("contrast").  The  output  raster  map  layers 
are  assigned  names  with  .1,  .2,  ...  .n  suffixes.  Ihe  current  geographic  region  definition  and  mask 
settings  are  respected  when  reading  the  input  raster  map  layers. 


Parameters: 
inputl  =name 
input  2  =name 
in  put  3  name 
input4=^inme 
input5  name 
input6  =name 
in  put  7  name 
inputK  name 
output  name 


Name  of  first  input  raster  map  layer. 

Name  of  second  input  raster  map  layer. 

Name  of  third  input  raster  map  lay  er. 

Name  of  fourth  input  raster  map  layer. 

Name  of  fifth  input  raster  map  layer. 

Name  of  sixth  input  raster  map  layer. 

Name  of  seventh  input  raster  map  layer. 

Name  of  eighth  input  raster  map  layer. 

The  cxitput  raster  map  layer  itamc  to  which  suffixes  are  added.  Each  output  raster 
map  layer  is  assigned  this  user- specified  name  with  a  numerical  (.1.  2,  ...  .n) 
suffix. 


Richards  (1986)  gives  a  guxl  example  of  the  application  of  principal  components  analysis  (pea)  to  a 
time  series  of  LANDSAT  images  of  a  burned  region  in  Australia. 

SEE  ALSO 

Rich;irds,  John  A.,  Remote  Sensing  Digital  Image  Analysis,  Springer- Verlag,  1986. 

Vali.  Ali  R..  Personal  communication,  Space  Research  (enter.  University  of  Texas,  Austin.  1990. 
i.cca,  i.class,  i.fft,  i.ifft,  true igensy stem,  r.cwar,  r.mapcalc 

AUTHOR 

David  Satnik,  GIS  Laboratory.  Central  Washington  University 
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NAME 

i. points  An  imagery  function  that  enables  the  user  to  mark  coordinate  system  points  on  an  image  to 
be  recti. iv-.  and  then  input  the  coordinates  of  each  point  for  creation  of  a  coordinate  transformation 
matrix.  The  transformation  matrix  is  needed  as  input  for  the  GRASS  program  i. rectify. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i  .points 

DESCRIPTION 

i.points  is  an  imagery  function  that  enables  the  user  to  mark  points  on  a  (raster)  image  to  be  rectified 
and  then  input  the  geographic  coordinates  of  each  point  for  calculation  of  a  coordinate  transformation 
matrix.  i.points  must  be  followed  by  use  erf  the  GRASS  program  i.rectify,  which  rectifies  the  image 
using  the  transformation  matrix  coefficients  calculated  by  i.points. 

Rectification  is  the  mappittg  (transformation)  of  an  image  from  one  coordinate  system  to  another.  Ihe 
geometry  of  an  image  extracted  into  a  GRASS  LOCATION  having  an  x,y  coordinate  system  is  not 
pi ani metric.  To  create  a  planimetric  image,  that  is,  to  convert  the  x,y  coordinate  system  into  a  standard 
coordinate  system  (for  example,  the  LT1M  coordinate  system  or  the  Stale  Plane  coordinate  system), 
points  from  a  map  having  the  standard  coordinates  must  Ire  associated  with  the  same  points  on  the 
image  to  be  rectified,  i.points  enables  the  user  to  mark  points  on  an  image  and  input  the  standard 
coordinates  for  that  point,  i.points  then  calculates  a  least  squares  regression  using  the  tu'o  ctxwxlinate 
systems  (x,y  and  standard)  for  the  marked  points.  A  matrix  containing  transformation  coefficients  is  the 
output  file  for  i.points. 

During  the  process  of  marking  prints  and  entering  map  coordinates,  the  user  can  compute  the  RMS 
(root  mean  square)  error  for  each  print  entered,  i.points  does  this  by  calculating  the  transformation 
equation  (the  same  one  that  is  crfculalcd  in  the  GRASS  program  i.rectify),  and  then  plugging  these 
results  into  an  equation  for  RMS  error. 

i.points  offers  a  zoom  option  to  fixate  precisely  the  print  to  lx-  marked  on  an  image.  This  program 
also  offers  the  user  the  option  of  acquiring  staixlard  coordinates  for  a  marked  pant  from  a  map  layer  in 
the  target  data  hasc. 

i. target  must  lx*  run  before  running  i.points  to  enable  the  PI  .Or  RAST1R  option  to  lx*  used  and  to 
identify  a  target  data  base  L(X’ATlON_NAMl-  and  MAPS1T  for  tlx*  rectified  im;tgc.  To  mn  i.points. 
a  graphics  monitor  is  required. 

Ihe  procedure  for  marking  prints,  entering  coordinates,  and  calculating  RMS  error  is  dcscrilxd  lx*low. 

Ihe  first  prompt  in  the  program  asks  the  user  for  the  imagery  group  to  lx  registered.  Note  tint  if 
i.target  is  not  run  before  i.points.  the  i.points  program  will  display  the  following  error  message: 

KRKOR:  Target  information  for  group  \spot\  missing 
Please  run  i.target  for  group  {spot | 

Alter  entering  the  group  to  lx  registered  tlx  terminal  screen  displays  tlx*  message: 

Use  mouse  now... 
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The  graphics  monitor  displays  the  following  screen: 


imagery  filename  (mag) 

target  filename  (mag) 

QUIT  ZOOM  PLOT  RASTER  ANALYZE 

A  pop-down  menu  like  that  shown  below  will  be  superimposed  on  the  left  half  of  the  screen: 


Double  dick  on  raster  map  layer 
to  be  platted 

Double  dick  here  to  cancel _ 


M  upset  demo 

spotdass 

spot.l 

composite 

spot  .2 

Any  single  raster  nuip  layer  in  the  imagery  group  may  be  used  on  which  to  mark  points,  anti  the  user 
can  mark  |xiints  on  more  than  one  raster  map  layer  in  the  imagery  group  to  accumulate  the  suggested 
minimum  number  of  12  |>>ints.  Any  raster  map  layer  in  the  imagery  group  can  be  rectified  (using 
i. rectify)  based  on  the  transformation  matrix  computed  from  these  points. 

The  imagery  file  chosen  by  the  user  is  displayed  in  the  upper  left  quadrant  of  tlic  screen. 

ZOOM 

To  magnify  the  displayed  file,  the  user  must  place  the  mouse  cross  liairs  on  tlie  word  ZOOM.  The 
following  menu  will  then  lx-  displayed  at  the  bottom  of  the  screen: 
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Cancel 


Box 


Point 


Select  type  of  ZOOM 


The  user  has  the  option  of  identifying  the  zoom  region  either  by  using  the  mouse  to  make  a  box,  or  by 
using  the  mouse  to  mark  the  two  diagonal  points  of  the  desired  region.  The  terminal  screen  will 
display  a  mouse  button  menu  to  guide  the  user  in  identifying  the  comer  points  of  the  region. 

MARKING  POINTS 

To  mark  the  points  on  the  image  that  correspond  to  the'  points  on  a  standard  coordinate  system  map,  the 
user  must  place  the  mouse  cross  hairs  on  the  corresponding  location  on  the  image  to  be  marked  and 
press  the  left  hand  button  on  the  mouse.  A  diamond  shaped  symbol  w  ill  be  marked  on  the  image.  Ihe 
user's  terminal  will  display  the  following  menu: 


Point  1  marked  on  the  image  at 
East:  1023.77 

North:  -164.41 

Enter  coordinates  as  east  north: 

Ihe  user  then  enters  the  casting  and  northing  (separated  by  a  space)  for  the  jxrint  marked  on  the  image. 
If  the  user  wishes  not  to  enter  a  coordinate,  he  or  she  ma\  simply  hit  RI’IUKN  to  return  control  to  the 
mouse;  the  marked  point  then  disappears. 

PLOT  KASTKR 

In  addition  to  acquiring  reference  points  from  a  sUuuLird  map.  the  user  has  the  option  ol  acquiring  the 
reference  points  from  a  raster  map  layer  in  the  target  tlata  base  1/X  ATK  )N_NAM1..  Ihe  elata  base- 
raster  map  layer  is  displayed  by  placing  the  mouse  cross  hairs  on  the  words  RASIT.R.  Ilu 

follow  ing  line  is  then  displayed  at  the  lx  Mom  of  the  graphics  monitor: 


Cancel  Indicate  which  side  should  he  jd fitted 


Which  side  of  the  graphics  monitor  is  te>  lx-  plotted  is  inelicateel  by  placing  the  mouse  cretss  hairs  oil  tlie 
lull f  of  the  graphics  monitor  screen  that  the  user  woulel  like  to  use-,  aid  pressing  the-  left  mouse  button. 
Ilie  following  pop-down  menu  will  be  superiiii|x>sed  on  the  hall  of  the'  serex'ii  that  was  chose-n: 
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Double  dick  on  raster  (cell)  map  layer 
to  be  plotted 

Double  dick  here  to  caned 


Mapeet  demo 

tmxedificd 

t  unclassified 

Mapset  PERMANENT 

elevation 

geology 

slope 

soils 

aspect 

roads 

streams 

airfidds 

After  the  raster  map  layer  is  displayed,  the  following  message  appears  at  the  bottom  of  the  graphics 
monitor: 


input  method  — >  |  keyboard 


screen 


If  the  user  wishes  to  use  the  plotted  raster  map  layer  only  as  a  comparative  reference,  then  the  keyboard 
can  be  chosen  as  tiro  means  to  input  coordinates  corresponding  to  the  marked  points  on  the  image.  This 
is  done  by  placing  the  mouse  cross  hairs  on  the  word  KEYBOARD  and  pressing  the  left  button  on  the 
mouse. 

If  the  user  selects  the  SCREEJN  option,  then  points  marked  on  the  image  will  automatically  lie 
associated  with  the  coordinates  from  the  corresponding  points  on  the  target  data  base  map  layer.  In  this 
option,  when  the  user  marks  a  point  on  the  inrage,  the  following  menu  is  displayed  at  the  tenranal: 


Point  5  marked  on  the  image  at 

East:  1023.77 

North:  -164.41 

Point  located  at 

East:  679132.57 

North:  4351080.67 

use  rmiuse  now... 
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lhe  user  then  uses  the  mouse  to  mark  a  corresponding  point  on  the  displayed  image  from  the  target 
data  base,  lhe  coordinates  for  the  target  data  base  map  layer  are  automatically  saved  as  the 
coordinates  corresponding  to  the  marked  point  on  the  image. 

ANALYZE 

After  a  number  of  points  have  been  marked  (4  to  7),  the  user  can  check  the  RMS  error  of  the  points 
marked  on  the  image.  'Ihis  is  done  by  placing  the  mouse  cross  hairs  on  the  word  ANALYZE  at  the 
bottom  of  the  graphics  monitor.  An  error  report  resembling  that  shown  below  is  superimposed  on  the 
graphics  monitor: 


# 

row 

error 

col 

target 

image 

east 

north 

target 

east 

north 

1 

0.0 

-0.9 

1.0 

1048-5 

-144.8 

679132.5 

4351080.6 

2 

0.4 

1.0 

1.3 

2153.1 

-567.2 

684314.7 

4399001.4 

3 

-1.2 

-0.5 

.6 

1452.8 

-476.5 

567841.4 

3457682.8 

4 

1.1 

0.5 

1.3 

1034.0 

-109.2 

677573.8 

4352626.4 

5 

-2.7 

14.0 

14.2 

1048.6 

-144.9 

679132.0 

4331080.7 

overall 

rms 

error: 

4.46 

lhe  following  menu  then  appears  at  the  bottom  of  the  graphics  monitor: 


1  DONE  1  PRINT  FILE  Double  click  on  point  to  be  imludcd/excludcd  } 


lhe  RMS  error  for  the  image  is  given  under  the  column  titled  "error”  and  subtitled  "row"  and  "col."  In 
the  above  report,  point  number  1  is  0.0  rows  and  -0.9  columns  front  the  predicted  hxation  calculated 
from  the  transformation  equation,  lhe  RMS  error  for  the  target  raster  map  layer  is  listed  under  the 
lieading  "target."  'Ihis  is  the  RMS  enror  for  the  east  and  north  coordinates  of  the  target  map  layer,  lx  it  it 
is  presented  in  the  table  using  one  general  value,  lhe  overall  RMS  error  is  displayed  at  the  bottom  of 
the  screen  in  meters.  Points  that  create  high  RMS  error  are  displayed  in  red  on  the  graphics  monitor 
(represented  here  in  italics). 

lhe  location  of  the  [xiint  marked  on  (lie  imagery  group  file  is  given  under  tlx’  heading  "image"  and  the 
subheadings  "east"  and  "north."  lhe  location  of  the  [xxnt  in  the  target  data  base  is  given  under  the 
heading  "target"  and  the  subheadings  "east"  and  "north.”  If  the  user  would  like  to  exclude  or  include  a 
point,  this  can  lie  accomplished  bv  placing  the  mouse  cross  hairs  on  the  |x >int  numlxr  to  lx1  included  (if 
the  point  is  absent)  or  excluded  (if  the  point  is  rlisplaved)  and  pressing  the  left  button  on  the  nuxisc 
twice.  When  a  point  is  excluded,  it  is  not  afterwards  included  in  the  calculation  ol  the  RMS  error,  or 
included  in  tlx-  final  transformation  matrix .  However,  it  can  lie  retrieved  within  i.points  at  any  time  It)' 
double  clicking  with  the  mouse  as  described  alxrvc. 

QUIT 

To  end  the  i.points  program  place  the  mouse  cross  hairs  on  the  word  Ol  1 1  ;  the  maiked  points 
(including  c<x>rdi nates)  w  ill  lie  saved. 

NOTES 

A  good  mle  of  thumb  is  to  mark  at  least  12  to  15  ]xrinls  that  are  evenh  distributed  over  the  entire 
imagery  group  file  in  order  to  obtain  ;ut  accurate  transformation  equation  loi  the  rcctilication  process, 
'lhe  RMS  error  max  increase  with  more  points  added,  but  the  transformation  equation  will  lx'  more 
accurate. 
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An  RMS  error  of  less  than  or  equal  to  approximately  one  resolution  unit  (pixel  or  cell)  for  the  image 
being  rectified  is  generally  considered  acceptable. 

In  order  to  use  a  digitizer  with  i.points,  at  least  one  digitizer  driver  besides  "none"  (the  on-screen 
digitizer)  must  be  available  in  the  digitcap  file. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 
g.mapsets,  i.group,  i.rectify,  iJarget 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i.rectify  -  An  imagery  function  that  rectifies  an  image  by  computing  a  coordinate  transformation  for 
each  cell  (pixel)  in  the  image  using  the  transformation  coefficient  matrix  created  by  the  GRASS 
program  i. points. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.rectify 

DESCRIPTION 

i.rectify  rectifies  an  image  by  using  the  transformation  coefficient  mahix  created  by  i.points. 
Rectification  is  the  process  by  which  the  geometry  of  an  image  is  made  planimetric.  'Ibis  is 
accomplished  by  mapping  (transforming)  an  image  from  one  coordinate  system  to  another.  In  i.rectify , 
the  coefficients  computed  by  i.points  are  used  in  an  equation  to  convert  x,y  coordinates  to  standard 
map  coordinates  for  each  cell  in  the  image.  'Ihe  result  is  an  image  with  a  standard  map  coordinate 
system.  Upon  completion  of  the  pregram  the  rectified  image  is  deposited  in  a  previously  targeted 
GRASS  LOCA'nON_NAME  and  MAPSET. 

The  first  prompt  in  the  pregram  asks  the  user  for  the  name  of  the  group  containing  the  raster  map 
layers  to  be  rectified. 

The  user  is  then  asked  to  select  the  map  layers)  within  the  group  to  be  rectified: 


Please  select  the  file(s)  to  rectify  by  naming  an  output  file 

spot.l  in  demo  . 

spot 3.  in  demo  . 

spot 3  in  demo  . 

spotclass  in  demo  spolrectify.. 
spotreject  in  demo  . 

(Enter  list  by  any  name  to  get  a  list  of  existing  raster  tiles) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <KSC>TO  CONTINUE 
(OR  <Ctrl-C> TO  CANCEL) 


More  than  one  raster  map  layer  may  lx-  rectified  at  a  time,  l  ath  raster  map  layer  should  have  a  unique 
outfit  file  name. 

Next  the  user  is  asked  to  select  out  til  two  geographic  region  sellings: 


Please  select  one  of  the  following  options 

1.  Use  the  current  geographic  region  definition  (window)  in  the  target  location 

2.  Determine  the  smallest  geographic  regi<m  definition  (window  )  which  covers  the  image 

> 


i.rectify  will  onlv  recti  !\  that  pinion  of  the  image  that  occurs  within  the  chosen  geographic  region 
setting,  f  Ally  that  portion  will  be  iclocalcd  in  tin-  target  data  base,  li  is  ihen  loiv  im|v>iianl  to  cheek 
the  current  geographic  region  settings  in  the  target  location  il  choice  nuinlx  i  one  is  sclct  ted. 
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NOTES 

i.rectify  will  run  in  the  background  and  notify  the  user  by  mail  when  it  is  finished.  The  process  may 
take  an  hour  or  more  dejiending  on  the  size  of  the  image,  the  number  of  files,  and  the  size  of  the 
geographic  region  definition. 

The  rectified  (raster)  image  will  be  located  in  the  target  LOCATION  when  the  program  is  completed. 
The  original  unrectilied  raster  map  layers  are  not  modified  or  removed. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 
i.grtxip,  i.points,  i. target 

AUTHOR 

Michael  Shapiro,  U.S.  Army  (^instruction  Kngineering  Research  Laboratory 
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NAME 

i.rectify.blk  -  An  imagery  function  that  ortho-rectifies  an  imagery  group  file. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.rectify.blk 

DESCRIPTION 

i.rectify.blk  allows  the  user  to  ortho-rectify  an  imagery  group  file.  An  imagery  photo  block  consists  of 
several  scanned  aerial  photographs  (raster  files)  of  a  common  area.  An  imagery  sub-bloek  is  a  subset  of 
these  raster  files.  Block  and  sub-blocks  of  imagery  groups  are  created  bv  the  GRASS  imagery  program 
i.build.blk. 

i.rectify.blk  guides  the  user  through  the  steps  required  to  ortho-rectify  a  single  sub- block  of  imagery 
groups  contained  in  a  block. 

I  he  first  menu  in  the  i.rectify.blk  program  asks  the  user  to  select  an  existing  block  ;uxl  sub-block.  If 
the  block  and  sub-block  do  not  yet  exist,  the  user  should  run  i.build.blk  before  running  i.rectify.blk. 

If  the  word  list  is  entered,  Hocks  or  sub-Hecks  that  Hive  already  Ixien  created  in  the  current 
LOCATION_NAME  and  MAPSEI'  will  be  listed. 

I  he  next  menu  in  i.rectify.blk  provides  the  user  with  the  following  options: 


1.  Select  another  sub-block 

2.  Compute  image-to-photo  transformation 

3.  Initialize  exposure  station  parameters 

4.  Compute  ortho-rectification  parameters 

5.  Ortho-rectify  the  selected  imagery  sub-block  files 

RETURN  to  exit 


Ihese  options  c;ui  lx:  described  as  follows: 

Select  another  suI>-bl(Kk 

If  option  number  1  is  chosen,  the  following  menu  is  displayed: 


Please  enter  the  sub-block  to  be  selected 
BLOCK:  block. 1 

SUB-BLOCK:  _ _ (enter  ’list’  for  a  list  of  sub-blocks) 


A  ITER  COMPLETING  ALL  ANSWERS,  HIT  <KSC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


If  the  word  list  is  entered,  subblocks  that  have  already  Ix-en  created  in  the  current  block  will 
lx:  displayed. 
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Compute  image-to-photo  transformation 

If  option  number  2  is  selec  ted,  image- to- photo  transformation  parameters  of  the  imagery  group 
in  the  selected  sub-block  arc  computed.  The  user  associates  reference  points  (fiducials,  reseau 
marks,  etc.)  with  their  known  photo  coordinates.  The  user  must  be  running  the  graphics 
monitor.  (Complete  documentation  for  this  option  is  available  under  the  manual  entry 
i. ortho. reference .  (  Hie  user  must  select  one  imagery  group  in  the  sub  block  to  initialize  the 
camera,  i.eamera  must  lx  used  to  create  a  camera  reference  file,  arid  i.build.blk  must  be  run 
ter  select  a  camera  reference  file  for  tlx*  block,  before  this  option  can  be  used.) 

Select  initial  exposure  station  parameters 

If  option  number  3  is  selected,  initial  camera  exposure  station  parameters  are  selected  or 
modified.  Complete  documentation  for  this  option  is  available  under  the  manual  entry 
i.ortho.initial. 

Compute  ortho-rectifuation  parameters 

If  option  number  4  is  selected,  ortho- rectification  parameters  for  the  imagery'  sub-block  are 
computed.  Here  control  points  are  marked  on  one  or  more  sub-block  imagery  raster  files  and 
associated  with  their  known  UI'M  coordinates.  Complete  documentation  for  this  option  is 
available  under  the  manual  entry  i. ortho. control. 

ortho-rectify  selected  sub-block 

If  option  number  5  is  chosen,  the  taster  files  referenced  by  the  imagery  sub-block  are  ortho- 
rectified.  Rectified  raster  files  will  be  created  in  the  target  location.  Complete  documentation 
for  this  option  is  available  under  the  manual  entry  i.ortho.rectify. 

NOTES 

The  i. rectify. blk  options  are  onlv  available  for  imagery  files  stored  under  the  user’s  current 
LOCATION. 

This  program  remains  under  alpha  testing.  It  resides  in  the  src.alpha  directory  and  must  be  compiled 
sep^ irately  by  the  user. 

SEE  ALSO 

i.build.blk,  i.eamera,  i.group,  i.orlho.control,  i. ortho. initial,  i.ortho.rectify,  i.ortho.reference 

AUTHOR 

Michael  Baba 
E®  A  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

i.rgbJiis  -  Red-green-blue  (tgb)  to  hue-intensity-saturation  (his)  function  for  image  processing. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.rgbJiis 
ijrgbJiis  help 

i.rgbJiis  red  input  =name  green_input -  name  blue,  input  =name 

hue  output  name  intensity  output  =nanu:  saturation  output  name 

DESCRIPTION 

i.rgb.his  is  an  image  processing  program  that  processes  three  input  raster  map  layers  as  red,  green,  and 
blue  components  and  produces  three  output  raster  map  layers  representing  the  hue,  intensity,  and 
saturation  of  the  data.  'I he  output  raster  map  layers  are  created  by  a  standard  red  green-blue  (igb)  to 
hue-intensity-saturation  (his)  color  transformation,  Inch  output  raster  map  layer  is  given  a  linear  gray 
scale  color  table.  Ihe  current  geographic  region  definition  and  mask  settings  are  respected. 

Parameters: 
r edinput  =name 
greeninput  -name 
blueinput  -name 
hue  output  =name 
intensity  .output  - name 
saturation. output  name 
SEE  ALSO 

hsv.rgb.sh,  i.his.rgb,  rgb.hsv.sh 

AUTHORS 

IXivid  Satnik .  ( ilS  lnl\>rator\,  Central  Wasliington  University, 

with  uc know iedgements  to  Ali  Vali.  Univ.  of  Texas  Space  Research  CVntei,  foi  the  core  routine. 


Input  raster  map  layer  representing  the  red  component. 
Input  raster  map  layer  representing  the  green  component. 
Input  raster  map  lay  er  representing  the  blue  component. 
Output  raster  map  layer  representing  hue. 

Output  raster  map  layer  representing  intensity. 

Output  raster  map  layer  representing  saturation. 
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NAME 

i. tape  miss  -  An  imagery'  function  that  extracts  Multi  spectral  Scanner  (MSS)  imagery  data  from  half¬ 
inch  tape. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.tapejnss 

DESCRIPTION 

i.tapeMiss  is  a  program  that  extracts  Multi  spectral  Scanner  (MSS)  imagery  data  from  tape. 

This  program  must  be  run  in  a  LOCATION_NAME  with  a  x,y  coordinate  system  (i.e.,  a  coordinate 
system  with  projection  0).  For  further  information  regarding  this  LOCATION __NAMF  refer  to  the 
manual  entry  for  imagery. 

The  first  prompt  in  i.tapeMiss  asks  the  user  for  the  tape  device  name.  This  is  sometimes  /dev/rmtO 
(for  a  half-inch  tape  with  a  tape  density  of  1600),  but  this  varies  with  each  machine. 

The  next  prompt  is: 


Please  mount  and  load  tape,  then  hit  RETURN  — > 


IMAGE  IDENTIFICATION  MENU 

The  first  menu  in  the  program  asks  the  user  for  information  about  the  data. 


please  enter  the  following  information 

Tape  Identification:  — 

Image  Description:  — 

Title  for  the  Extracted  Raster  (Cell)  Files:  — 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 

(OR  <Orl-C>TO  CANCEL) 


This  prog  nun  automatically  enters  the  scene  ID  number  and  the  date  of  the  image  into  the  field  for 
Tape  Identification.  The  sun  angles  are  automatically  entered  into  the  field  for  Image  Description. 
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Ttte  second  menu  is: 

MSS  TAPE  EXTRACTION 

please  select  the  desired  tape  window  (geographic  region  definition)  to  extract 

first  row: _ (1-2984) 

last  row: _ (1-2984) 

first  col: _ (1  -3548) 

last  col:  _ (1-3548) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESOTO  CONTINUE 
(OR  <Ctrl-C>  TO  CANCEL) 

'Ilie  numbers  in  parentlieses  arc  the  total  nuinlxr  of  rows  and  columns  on  the  tape  including  filler 
(zeros).  This  information  and  additional  information  can  also  lx-  obtained  by  miming  the  GRASS 
program  i.tape.mss.h,  which  reads  the  header  information  on  an  MSS  tape.  Any  subset  of  the  image 
on  tape  may  lx-  extracted.  For  a  discussion  of  row  and  column  extraction,  see  the  subheading  titled 
ROW  AND  COLUMN  FXfRACTlON  below. 

The  next  menu  is: 

please  make  an  x  by  the  hands  you  want  extracted 

_ I 

_ 2 

_ 3 

_ 4 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Orl-C>  TO  CANCEL) 

MSS  imagerv  lias  4  kinds,  but  (lie  user  nia\  want  io  extract  on!\  a  subset  ol  these  bands  See  the 

subheading  in  this  entrx  tilled  R(  )W  AND  COLUMN  L.XTRAO  K  )N. 

Ihe  user  then  is  asked  to  enter  the  |>reli\ /group  for  the  kind  hies  to  lxi  created.  Iliis  naiiK'  will  precede 
each  hand  file  extracted  into  CRASS.  For  example.  ii  three  kinds  are  extracted  the  lolloping  three 
(raster)  hand  files  will  result: 

prefunanw .  I 
prcjixnanw  .2 
prcjixnamc  .3 

Whatever  prejixnunu’  is  s|xvilied  will  also  automatic. ill\  k  come  the  name  lor  die  inucciv  croup  file 
king  created.  Inch  image  (i.c..  each  mu  ol  i  .tape  .nus  t  sh.  mid  Is  coon  a  unii|ii>  pi-  Io.' 'croup  name. 

Ihe  ixtracti-i.  process  will  k-'in  In  lirst  skippinc  tin  uunik  r  -  I  spciti-d  tiles.  a-Kanemg  I-'  the 

starting  row.  and  dicn  i- adinc  ill-  tap  Ihe  p  ro  ir  i  -  -mpK  in  -ii  -  I  tin  «  xti.icti-  -n  i'  dopin' -d  -  n  tin 

m  rei  n.  II  m-  >!<  than  on.  lap-  is  f,  ijuin  .  I  v  -ie  lit-  imi.ic-  .  tin  pt-*a.im  il!  pnoe  .m<  I  ;  • : I .  -i  •  d.  ,  i 

ti  -  m-  mill  tin  n-  \i  tap  . 

Ihe  -  xtraeted  fni'ti  rt  band  libs  v-  ill  k-  list-  ,1  .is  ia'l«  i  ui.-p  l.c><  is  avatl.ikle  in  lit-  t  mi-'iit  M  M  ’SI  I 

and  max  lx-  di-pl.c.  -  -I  ionic  tli>  <  iRASN  commands  <1. display.  il  rasi  or  /  points 
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NOTES 

After  extracting  an  image  from  tape,  the  geographic  region  definition  in  the  x,y  coordinate 
L0CA'I10N_NAME  will  be  set  based  upon  the  extracted  rows  and  columns  from  the  tape.  The 
relationship  between  the  image  rows  and  columns  and  the  geographic  coordinates  of  the  region  is 
discussed  in  the  manual  entry  for  imagery. 

Ibis  program  is  interactive  and  requires  no  command  line  arguments. 

ROW  AND  COLUMN  EXTRACTION 

Ihe  display  optioas  in  GRASS  allow  the  user  to  locate  rows  and  columns  on  the  digital  image.  If 

enough  disk  space  is  available,  one  band  of  an  entire  image,  or  one  band  of  a  portion  of  an  image 

known  to  contain  the  area  of  interest,  can  be  extracted  and  displayed.  The  measurements  option  in 
d.display,  or  d.where  (following  the  use  of  d.rast )  will  echo  x  and  y  coordinates  to  the  screen.  (These 
coordinates  will  display  negative  numbers  in  the  north-south  direction,  but  ignoring  the  negative  sign 
will  yield  the  row  number.)  See  the  imagery  manual  entry  for  further  explanation. 

If  a  photograph  of  the  digital  image  is  available,  the  rows  and  columns  to  be  extracted  can  be 

determined  from  it  by  associating  inches  with  the  total  number  of  known  rows  and  columns  in  the 

scene.  For  example,  if  the  total  length  of  the  photograph  is  12  inches,  the  total  number  of  rows  on  the 
tape  is  2000,  and  the  northwest  comer  of  the  area  of  interest  begins  2  inches  from  the  top  of  the  photo, 
then: 


12  in.  /  2000  rows  =  2  in.  /  x  rows 
x  =  :  33 .333 

The  northwest  comer  of  the  area  of  interest  starts  at  row  333.  The  starting  row,  ending  row  starting 
column,  and  ending  column  can  be  calculated  in  this  manner. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.display,  d.rast,  d.where,  i.group,  i. points,  iJapejnss.h,  i.tape.other,  i.tape.tm,  imagery 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Gxistmction  1  ngineering  Research  laboratory 
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NAME 

i.tapejnss.h  -  An  imagery  function  that  extracts  header  information  from  LANDSAT  Multispectral 
Scanner  (MSS)  imagery  data  stored  on  half-inch  tape. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.tapejtnssJi 
i.tapejuissJi  help 
i.tapeans&h  tape  _drive_name 

DESCRIPTION 

i.tapejnss.h  reads  the  header  information  on  a  Multispectral  Scanner  (MSS)  tape.  Ihis  program  reads 
the  specified  input  file  (the  computer-compatible  tape  tape_drive_name),  and  by  default  displays  the 
output  to  the  user’s  terminal.  I  he  user  may  redirect  output  to  a  file  by  using  the  UNIX  redirection 
mechanism.  For  example: 

i.tapejnss.h  /devArntO  >h.out 

The  name  of  the  tape  drive  depends  on  the  computer  being  used. 

This  program  can  be  run  either  non-intcnictivelv  or  interactively.  Ihe  user  can  run  the  program  by 
specifying  program  arguments  on  the  command  line.  Alternately,  the  user  can  simply  type 
i.tapc-mssJi  on  the  command  line,  without  program  arguments.  In  this  event,  the  program  will  prompt 
the  user  to  enter  a  tape  device  name  using  the  standard  user  interface  described  in  the  manual  entry  for 
parser. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

i.tape.mss  anil  parser 

AUTHOR 

Michael  Shapiro.  U.S.  Army  Construction  Ingineering  Research  laboratory 
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NAME 

i.tape. other  -  An  imagery  function  that  extracts  scanned  aerial  imagery  (NHAP,  etc.)  and  SPOT 
imagery  from  half- inch  tape. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i.tape. at  her 

DESCRIPTION 

i.tape. other  is  a  generic  program  that  extracts  imagery  from  tape  using  the  tape  description  that  is 
input  by  the  user. 

This  program  must  be  run  in  a  LOCATION_NAME  with  a  x,y  coordinate  system  (i.e.,  a  coordinate 
system  with  projection  0).  For  further  information  regarding  this  LOCATION_NAME  refer  to  the 
manual  entry  for  imagery. 

The  fust  prompt  in  i.tape. other  asks  the  user  for  the  tape  device  name.  This  is  sometimes  /devAmtO 
(for  a  density  of  1600),  but  this  varies  with  each  machine. 

The  next  prompt  is: 

Please  mount  and  load  tape,  then  hit  RETURN  —  > 

IMAGE  IDENTIFICATION  MENU 

The  first  menu  in  the  program  asks  the  user  for  information  about  the  data. 


please  enter  the  following  information 
Tape  Identification: 

Image  Description: 

Title  for  the  Extracted  Raster  (Ceil)  Files: 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Orl-C>  TO  CANCEL) 


TAPE  LAYOUT  MENU 

The  next  menu  asks  for  the  physical  layout  of  the  tape. 


GRASS  4.0  (Summer  1691) 


U  S.  Annv  (TRl. 


159 


i.tape.olher 


GRASS  Reference  Manual 


i  .tape  .other 


GENERIC  TAPE  EXTRACTION 


tape  layout 

_0_  number  of  tape  files  to  be  skipped 

_0_  number  of  records  in  the  remaining  files  to  be  skipped 

band  files 

0  number  of  bands  on  the  tape 

data  format 

_  band  sequential  (BSQ)  |  mark  one  with  an  x 

_  band  interleaved  (BIL)  | 

_0  if  you  select  BSQ  format  and  all  the  bands  are  in  a  single  file 

enter  the  total  number  of  records  in  the  file.  Otherwise  enter  0 

__0_  length  (in  bytes)  of  the  longest  record  on  the  tape 

AFTER  COMPLETING  ALL  ANSWERS,  IIIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


number  of  tape  files  to  be  skipped 

If  tlicre  are  files  at  the  beginning  of  the  tape  that  are  not  image  data,  they  c;ui  lie  skipped. 
Sometimes  information  that  comes  with  a  tape  will  indicate  the  number  of  header  liles  or 
records  on  the  tape.  Ihe  GRASS  utility  nuexanine .tape  will  also  provide  this  information. 
The  record  length  is  the  number  of  columns  in  the  im;ige.  while  the  number  of  records  is 
the  number  of  rows  in  the  image.  NIIAP  i  mag  on  and  usually  most  scanned  aerial  imagery  do 
not  have  ta[x-  headei  files,  but  this  should  lx?  checked.  SI’(  >1  imager,  has  two  tiles  that  should 
be  skipped  on  the  first  tape,  and  one  file  to  be  skip|xd  on  the  second  tape?  (of  a  two  tape  set). 

number  of  records  in  the  remaining  files  to  be  skipped 

If  the  files  that  contain  the  image  Ix-gin  with  non  image-  elata.  these  records  can  also  lx- 
skipped.  Iliis  is  usually  zero  for  most  data  tyjx-s.  SI’(  fl  'imagery  store-el  in  IriOObpi  has  one 
heaeler  record  in  tile  image  file-  oil  eaelt  ta[x-  tliat  sh» nilel  lx-  skip|Xel. 

number  of  bands  on  the  tape 

Most  aerial  imagery  have  three  b;u  kb.  but  satellite  simulator  data  may  have  more.  Sit  >1  has 
three  banels  as  a  stanelarel.  Ihe  te»tal  numlx-r  of  battels  e>n  the-  ia|x-  shexilel  lx-  spceilie-el  lu  re,  not 
just  tlie  numlx-r  tliat  will  lx  extracted. 

data  format 

Ihe-  twe)  formats  that  imagery  elata  are-  most  e-ommonl\  stored  in  are  called  band  interleaved 
formal  (lill.)  anel  band  sequential  tonnat  (BSO)  In  Hit  lomi.it.  eaeh  reeorel  on  tlx-  ta|x- 
contains  one  line  lor  one  hand  of  elata.  If  tlx-  elata  contains  three  baixls.  then  tlx-  lust  live- 
rccorels  will  look  like  this: 


batxl  i .  e  l 
baixl  ;.  line  1 
batxl  v  liiu-  I 
battel  i .  line  2 
batxl  .' .  line-  2 


|i»(i 
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In  BSQ  format,  all  lines  of  one  band  are  stored  together  on  a  tape,  followed  by  all  lines  of 
another  band,  followed  by  all  lines  of  the  next  band,  etc.  These  data  are  stored  as  if  they  were 
in  a  one  band  BIL  format: 


band  1,  line  1 
band  1,  line  2 
band  1,  line  3 


band  2,  line  1 
band  2,  line  2 

band  2,  line  156 
band  2,  line  157 

Each  pixel  contains  one  byte  and  there  is  one  line  per  record.  BSQ  format  is  the  format  that  is 
usually  created  by  optical  scanning  devices  when  they  scan  photographs,  but  not  all  digitized 
aerial  imagery  are  stored  in  this  formal.  The  format  of  the  data  is  usually  written  on  the 
exterior  of  the  tape;  this  should  be  checked. 

length  (in  bytes)  of  the  longest  record  on  the  tape 

This  must  be  set  to  the  number  of  bytes  in  the  longest  data  record.  It  is  used  to  determine  how 
large  a  buffer  to  use  for  reading  the  tape.  This  value  can  be  obtained  using  m.examne.tape. 

BAND  EXTRACTION  MENU 

The  user  is  then  asked  to  mark  an  x  beside  the  bands  to  be  extracted.  See  the  subheading  in  this  entry 
entitled  ROW  AND  COLUMN  EXTRACTION. 


please  mark  an  x  by  the  bands  you  want  extracted 

_ 1 

_ 2 

_ 3 

_ 4 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


i>kefixa;roup  name 

Ilie  user  is  asked  to  enter  the  prefix /group  for  the  (raster)  hand  files  to  be  created.  This  name  will 
precede  eacli  band  file  extracted  into  GRASS.  For  example,  if  three  bands  are  extracted,  the  following 
three  band  files  will  result: 


prejixname.l 

prefixname.2 

prejixname.3 

The  specified  prefixname  will  also  automatically  become  the  name  for  the  imagery  grixip  file  being 
created.  Each  im;<gc  (i.e.,  each  run  of  i.tape. other)  should  be  given  a  unique  prefix/group  name. 
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ROW  AND  COLUMN  MENU 

Finally,  the  starting  iw,  ending  row,  starting  column  and  ending  column  are  required.  This  allows  the 
user  to  extract  any  subset  of  the  image  from  the  tape. 


EXTRACT 

please  select  deared  tape  window  (geographic  region  definition)  to  extract 

start  row:_0_ 
end  row:_0_ 


start  col:_0_ 
end  col:_0_ 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Orl-C>TO  CANCEL) 

The  extraction  process  will  begin  by  first  skipping  the  number  of  specified  files,  advancing  to  the 
starting  row,  and  then  reading  the  tape.  The  percent  completion  of  file  extraction  is  displayed  on  the 

screen. 

Following  the  extraction,  the  extracted  band  files  will  be  listed  as  raster  map  layers  available  in  the 
current  MAPSFT.  These  raster  map  layers  may  be  displayed  individually  using  the  GRASS  commands 
(l.display,  d.rast  or  i.points. 

NOTES 

After  extracting  an  image  from  tape,  the  geographic  region  in  the  x,y  coordinate  LOCATION_NAME 
will  be  set,  based  upon  the  extracted  rows  and  columns  from  the  tape.  The  relationship  between  the 
image  row  s  and  columns  and  the  coordiates  bounding  the  geographic  region  is  discussed  in  the  imagery 
manual  entry. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

ROW  AND  COLUMN  EXTRACTION 

The  display  options  in  GRASS  allow’  the  user  to  locate  rows  and  columns  on  the  digital  image.  If 
enough  disk  space  is  available,  one  band  of  an  entire  image,  or  one  band  of  a  portion  of  an  image 
known  to  contain  the  area  of  interest,  can  be  extracted  and  displayed.  The  measurements  option  in 
d.display,  or  d.where  (following  a  nut  of  d.rast )  will  echo  x  and  v  coordinates  to  the  screen.  (These 
coordinates  will  display  negative  numbers  in  the  north-south  direction  but  ignoring  the  negative  sign 
will  yield  the  row  number.  See  the  imagery  manual  entry  for  further  explanation.) 

If  a  photograph  of  the  digital  image  is  available,  the  rows  and  columns  to  lie  extracted  can  be 
determined  from  it  by  associating  inches  will)  the  total  number  of  known  rows  and  columns  in  the 
scene.  For  example,  if  the  total  length  of  the  photograph  is  12  inches,  the  total  number  of  rows  on  the 
tape  is  2000,  anti  the  northwest  comer  of  the  area  of  interest  begins  2  inches  from  the  top  of  the  photo, 
then: 


12  in.  /  2000  rows  =  2  in.  /  x  rows 
x  =  333333 

The  northwest  comer  of  tire  area  of  interest  starts  at  row  333.  'Hie  starting  row  ,  ending  row,  starting 
column,  and  ending  column  can  be  calculated  in  this  manner. 
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SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.display,  d.rast,  d.where,  i.group,  i.points,  iJapemss,  i Jape. mss Ji,  iJapeJm,  imagery, 
nuexanine.tape 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

i.tape.tm  -  An  imagery  function  that  extracts  LANDSAT  Ihematic  Mapper  (TM)  imagery  from  half¬ 
inch  tape. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

LtapeTm 

DESCRIPTION 

i.tape.tm  is  a  program  that  extracts  LANDSAT  Thematic  Mapper  (TM)  imagery  from  half-inch  tape. 

This  program  must  be  run  in  a  LOCATTON_NAME  with  a  x,y  coordinate  system  (i.e.,  a  coordinate 
system  with  projection  G).  For  further  information  regarding  this  LOCA'TION_NAMF  refer  to  the 
imagery  manual  entry. 

The  first  prompt  in  i.tape.tm  asks  the  user  for  the  tape  device  name.  This  is  sometimes  /dev/mitO  (lor 
a  half-inch  tape  having  a  density  of  1600  bpi),  but  this  varies  with  each  machine. 

The  next  prompt  is: 


Please  mount  and  load  tape,  then  hit  RETURN  --> 


IMAGE  IDENTIFICATION  MENU 

The  first  menu  in  the  program  asks  the  user  for  information  about  tlie  data. 


please  enter  the  following  information 

Tape  Identification:  — 

Image  Description:  — 

Title  for  the  Extracted  Raster  (Cell)  Files:  — 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 

(OR  <Ctrl-C>  TO  CANCEL) 


'litis  program  automatically  enters  the  scene  II)  numlier  into  the  field  for  Tajte  Identification.  Hie 
mission,  path,  row,  quadrant,  date,  and  whether  the  image  is  corrected  is  automatically  entered  into  the 
field  for  Image  Description. 
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Ihe  second  menu  is: 


THEMATIC  MAPPER  EXTRACT 

please  select  the  desired  tape  window  (geographic  region  definition)  to  extract 

first  row: _ (1-2984) 

last  row: _ (1-2984) 

first  col: _ (1-4220) 

last  col:  _ (1-4220) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 

Ihe  numbers  in  parentheses  are  the  total  number  of  rows  and  columns  on  the  tape  including  zeros 
(filler).  Ibis  information  and  additional  information  can  also  he  obtained  by  running  the  program 
rn.examine.tape.  nuexamine.tape  will  read  any  tape  and  provide  the  user  with  the  number  of  files  on 
a  tape,  the  number  of  records  on  a  tape,  and  the  record  lengthes.  Any  subset  of  the  image  on  the  tape 
mav  lx  extracted.  For  a  discussion  of  row  and  column  extraction  see  the  subheading  entitled  ROW 
AND  COI  .UMN  1-XrRACnON  below. 

lire  next  menu  is: 


please  make  an  x  by  the  bands  you  want  extracted 

_  1 

_ 2 

_ 3 

_ 4 

_ 5 

_  6 

_  7 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 

IV!  imagery  has  seven  Ixuids,  Ixit  the  user  may  want  to  extract  only  a  subset  of  these  bands.  See  the 
subheading  in  this  entry  entitled  ROW  AND  COLUMN  I-XTRACIION. 

Ihe  user  then  is  asked  to  enter  the  prefix/gmup  for  the  raster  Ixind  files  to  lx  created.  This  name  will 
| recede  each  band  file  extracted  into  GRASS.  Lor  example,  it  three  baixts  are  extracted  the  following 
three  band  files  will  result: 


prejixname.  I 
prejixname.2 
prejixname. 3 

Hie  specified  prejixname  will  also  automatically  lvcomc  the  name  for  the  imagery  group  file  being 
created.  I  nch  image  or  quad  (i  e..  each  run  of  i.tape.tm)  should  lx'  given  a  unique  prelix/grixip  name. 
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The  extraction  process  will  begin  by  first  skipping  the  number  of  specified  files,  advancing  to  the  first 
band  requested,  and  then  reading  the  tape.  After  extracting  the  requested  rtr  s  and  columns  for  each 
band,  the  pmgram  creates  support  files  for  the  raster  band  map  layer.  Ihe  percent  completion  of  the 
extraction  is  displayed  on  the  screen.  Because  I’M  imagery  is  divided  into  four  quads  and  is  sirred  in 
multiple  tape  sets,  the  program  is  designed  to  read  one  quad  at  a  time.  Ihe  number  of  tapes  required  to 
store  one  quad  depends  on  the  number  of  bytes  per  inch  in  which  the  data  is  stored.  If  more  than  one 
tape  is  required  to  store  one  quad,  the  program  will  pause  and  inform  the  user  to  mount  the  next  tape. 

Ihe  extracted  band  files  will  be  listed  as  raster  map  layers  available  in  the  current  MAPSIT  ;uxl  may 
be  displayed  using  the  GRASS  commands  d.display ,  d.rast  or  i. points. 

NOTES 

After  extracting  an  image  from  tape  the  geographic  region  definition  in  the  x,y  coordinate 
I .(X’ATION_NAMI  will  be  set  based  upon  the  extracted  rows  and  columns  from  the  tape.  The 
relationship  between  the  image  rows  and  columns  and  the  coordinates  of  tire  geographic  region  is 
discussed  in  the  imagery  manual  entry. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

ROW  AND  COLUMN  EXTRACTION 

The  display  options  in  GRASS  allow  the  user  to  hxtate  rows  and  columns  on  the  digital  image.  If 
enough  disk  space  is  available,  one  band  of  an  entire  image  or,  one  band  of  a  portion  of  an  image 
known  to  contain  the  area  of  interest,  can  lx  extracted  and  displayed.  The  measurements  option  in 
d.display,  or  d.where  (following  use  of  d.rast )  will  echo  x  and  y  coordinates  to  the  screen.  (These 
coordinates  will  display  negative  numbers  in  the  north  south  direction,  but  ignoring  the  negative  sign 
will  yield  the  row  number.)  See  the  imagery  manual  entry'  for  further  explanation. 

Bach  quad  of  a  TM  image  contains  filler  on  Kith  the  left  and  right  sides  of  the  quad.  The  user  may 
want  to  identify  the  row  and  column  ihuhIxts  in  order  to  exclude  the  filler.  This  filler  w  ill  otherwise  be 
extracted  with  the  image  and  take  up  unnecessary  disk  space. 

If  a  photograph  of  the  digital  image  is  available,  the  rows  and  columns  to  lx  extracted  can  lx- 
detennined  from  it  by  associating  inches  with  the  total  numlxr  of  known  rows  and  columns  in  the 
scene.  For  example,  if  the  total  length  of  the  photograph  is  12  inches,  the  total  numlxr  of  rows  on  the 
tape  is  2000,  and  the  northwest  comer  of  the  area  of  interest  begins  2  inches  from  the  top  of  the  photo, 
then: 


12  in.  /  2000  row  s  =  2  in.  /  x  rows 
x  =  333.333 


The  northwest  comer  of  the  area  of  interest  stalls  at  row  333.  The  starting  row.  ending  row,  starting 
column,  and  ending  column  c;ui  lx  calculated  in  this  manner. 

SEE  ALSO 

GRASS  Tutorial:  Image  Troc.essing 

d.display,  d.rast,  d.where,  i.group,  i.points,  i. tape. mss,  i. tape. mss. h.  i. tape. other,  imagery, 
m.examine  .tape 

AUTHOR 

Michael  Shapiro,  U  S.  Amiv  Construction  I  ngineerinu  Research  I  ahoiaton 


( iRASS  4.0  (Summer  1001) 


l  '  S  Anm  <  I  Rl 


IK. 


i. target 


GRASS  Reference  Manual 


i.  target 


NAME 

i.target  -  An  interactive  imagery  function  that  establishes  a  GRASS  target  location  and  mapset  for  an 
imagery  group. 

(GRASS  Image  Processing  Program) 

SYNOPSIS 

i  .target 

DESCRIPTION 

i.target  taigets  an  imagery  group  to  a  GRASS  data  base  location  name  and  mapset.  During  the  imagery 
program  i.rectify,  a  location  name  and  mapset  are  required  into  which  to  transfer  the  rectified  file  just 
prior  to  completion  of  the  program;  i.target  enables  the  user  to  specify’  this  location,  i.target  must  be 
mn  before  i. points  and  i.rectify. 

The  first  prompt  in  the  program  asks  the  user  for  the  name  of  the  imagery  group  that  needs  a  target. 
Ihe  imagery  group  must  be  present  in  the  user’s  current  mapset. 

I  he  following  menu  asking  for  the  target  IjOCATION  NAMli  and  MAPSEr  is  displayed: 

Please  select  the  target  LOCATION  and  MAPSET  for  group  <Spot > 

CURRENT  LOCATION:  location _ 

CURRENT  MAPSET:  demo _ 

TARGET  LOCATION:  _ 

TARGET  MAPSET:  _ 

(Enter  list  for  a  list  of  location  names  or  mapset s  within  a  location) 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


Ai  iiiKigery  group  may  lx-  targeted  to  anv  GRASS  location. 

NOTES 

lliis  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

Grass  Tutorial:  Image  Processing 
i.group,  i.points,  i.rectify 

AUTHOR 

Michael  Shapiro.  US.  Army  Construction  Engineering  Rese;irch  laboratory 
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NAME 

i.zc  -  Zero-crossing  "edge  detection"  raster  function  for  image  processing. 

(GRASS  Image  Processing  Program ) 

SYNOPSIS 

i.zc 

i.zc  help 

i.zc  input_map=/ui/7k’  zc_map=n ame  [width ~value\  \ threshold  —value]  [orientations=vo/ue] 
DESCRIPTION 

i.zc  is  an  image  processing  program  used  for  edge  detection.  The  raster  map  produced  shows  the 
location  of  "boundaries"  on  the  input  map.  Boundaries  tend  to  be  found  in  regions  of  changing  cell 
values  and  tend  to  nut  perpendicular  to  the  direction  of  the  slope.  I  he  algorithm  used  for  edge 
detection  is  one  of  the  "zerocrossing"  algorithms  and  is  discussed  briefly  below. 

This  program  will  be  run  interactively  if  the  user  types  i.zc  without  program  arguments  on  the 
command  line.  In  this  event,  the  program  will  prompt  the  user  for  p;irameter  values  using  the  standard 
interface  described  in  the  manual  entry  for  parser.  Alternately,  the  user  can  nin  the  program  non- 
interactively  by  specifying  program  parameter  values  on  the  command  line. 


Parameters: 


input  map=name 
zc  map  =name 
width  rvalue 


Name  of  input  raster  map  layer. 

btune  of  raster  map  layer  to  be  used  for  zero-crossing  values. 

This  parameter  determines  the  x-y  extent  of  the  Gaussian  filter.  I  he  default  viilue 
is  9;  higher  and  lower  values  can  lx;  tested  by  the  user.  Increasing  the  width  will 
result  in  finding  "edges"  representing  more  gradual  changes  in  cell  values. 

I  Xf  atilt:  9 


threshold  —value  Ihis  parameter  determines  the  "sensitivity"  of  the  Gaussian  filter.  The  default 
value  is  10;  higher  and  lower  values  can  lx:  tested  by  the  user.  Increasing  the 
threshold  value  will  result  in  fewer  edges  being  found. 

IXfault;  10 


orientations=vo/ue  lhis  value  is  the  numlxr  of  azimuth  directions  the  cells  on  the  ouljxit  raster  map 
layer  are  categorized  into  (similar  to  the  aspect  raster  map  layer  produced  by  the 
r.. slope. aspect  program).  For  example,  a  value  ol  16  would  result  in  detected 
edges  being  categorized  into  one  ol  16  bins  depending  on  the  direction  of  the 
edge  at  that  )X>int. 

IXfault.  1 


Ihe  current  region  definition  and  mask  settings  tire  respected  when  reading  tlx-  input  map. 

NOTES 

Ihe  procedure  to  find  the  "edges"  in  the  image  is  as  follows:  1)  Ihe  Fourier  transfonn  of  the  image  is 
taken.  2)  Ihe  Fixirier  transform  of  the  I  apiarian  of  a  two-dimensional  (iaussiau  function  is  used  to 
filter  the  transfonned  image,  3)  Ihe  result  is  run  through  an  inverse  Fixirier  transform.  4)  Ihe  resulting 
image  is  traversed  in  search  of  places  where  the  image  changes  Irom  positive  to  negative  or  from 
negative  to  positive,  5)  Inch  cell  in  the  map  where  the  v.ilue  crosses  zero  (with  a  change  in  value 
greater  I  km  the  threshold  value)  is  marked  as  an  edge  and  an  orientation  is  assigned  to  it.  Ihe 
resulting  raster  map  layer  is  ixitput. 

SEE  ALSO 

Personal  communication  Ixtlvveen  program  author  and  Ali  R.  Vali.  Space  Research  (  enter,  liiiversitv  ol 
Texas.  Austin,  1990. 
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i.fft,  rjnapcalc,  r.mfUter,  rjlopeAspect  and  parser 
AUTHOR 

D&vid  Satnik,  CHS  Laboratory,  Central  Washington  University 
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NAME 

nudatunushift  -  Datum  shift  program. 

(GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

m.datum^shift  lat  =dd.mnuss{n | .?}  Ion =dd.mnuss{e |  w}  is=input_  spheroid  os=output ^spheroid  dx  =xshifl 
dy  =y shift  dz=zshift 

DESCRIPTION 

nudatunushift  returns  geographic  coordinates  based  on  a  different  spheroid  (and  datum)  than  the  one 
used  to  obtain  the  original  coordinates. 

Ihe  input  and  output  spheroids,  is  and  os.  are  the  spheroids  for  two  different  datums.  J lie  injxit 
spheroid  is  the  one  on  which  the  original  coordinates  are  based.  Die  output  spheroid  is  that  on  which 
the  resultant  coordinates  will  lx-  based,  Ihe  "shifting"  occurs  between  the  two  datums.  Ihe  shift 
values,  dx,  dy,  and  dz,  are  constants.  They  indicate  the  me;ui  differences  between  points  in  the  second 
datum  versus  the  first  as  measured  in  meters. 

Ihe  list  of  spheroids  available  is  somewhat  dynamic.  It  may  not  contain  exactly  tlte  ones  listed  below. 

To  determine  the  current  list  of  possible  spheroids,  type  in  the  command: 

m.datum.shift  lat  On  loo  Ow  dx=0  dy=0  dz=0  is  -help  os  help 

A  list  of  available  spheroids  will  lx:  printed  on  the  screen.  If  the  spheroid  desired  is  not  on  the  list,  the 
values  for  the  semi-major  axis  and  the  eccentricity  squared  for  the  spheroid  may  lx-  entered  in  place  of 
a  spheroid  name  in  the  following  format: 

s  =a  =semi-major_axis  ,e  ^eccentricity. squared 

SOME  POSSIBLE  SPHEROIDS 

(The  on-line  listing  includes  only  the  spheroid  names ) 


Spheroid 

Comnxtnlv  used  for: 

Semi  major  axis 

Eccentricity  sqrd 

australian 

■Australia 

637X160.0 

0.(K)669454 19 

bessel 

Japan 

6377739.155 

0.(K»66743722 

clark66 

N.  Anerica 

637X206.4 

0.00676X658 

cl  ark 80 

1  ranee,  Africa 

637X249.145 

0.1X16X035 1 13 

everest 

India.  Bumia 

6377276345 

0.0066378466 

international 

litro|>e 

637X3X8.0 

0.(K 1672267 

vvgs72 

worldwide  coverage 

637X135.0 

0.0066943 I 777S 

EXAMPLE 

m.datum.shift  latOn  Ion^l75w  is  =clark66  os=wgs72  dx  --22  dy  157  dz  — 176 

Results: 

iat  -0.(X).05.72999N 
Ion  M74-59.55.004133W 

NOTES 

Essenlialh .  the  program  follows  tltese  step--.  Ihe  original  piint.  as  Aimed  b,  a  latitude  md  a 
longitude,  is  convened  to  geocentric  coordinates.  Ihe  shill  values  are  added  to  the  geocentric 
coonlinales.  Ihe  suimned  values  are  then  converted  to  latitude  and  longitude  based  <>n  the  output 
spheroid. 

lor  a  brief  discussion  of  spheroids  and  datums  see  m.ll2u  lor  a  brie  I  discussion  o|  ee.seiiliic 
icxxdinates  see  m.U2g(  . 
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This  remains  under  testing  and  is  still  an  experimental  program.  It  is  part  of  an  initial  effort  to 
incorporate  geographic  coordinates  into  GRASS. 

SEE  ALSO 

m.gc2U,  null2gc,  m.H2u,  m.u2ll 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

m.dem.examine  -  Provides  a  terse  description  of  USGS  Digital  Hevation  M(xlel  (DEM)  data  tiles 
stored  on  half-inch  magnetic  tape. 

(GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

m.dem. examine  input  name  block  size  —value 
DESCRIPTION 

nudemexamine  reads  Digital  1:1  ovation  Model  (DEM)  terrain  elevation  data  produced  arxl  supplied  by 
the  USGS  from  the  input  file  specified  by  name ,  in  the  block  size  specified  by  value.  If  no  input  file  is 
named  on  the  command  line,  the  program  assumes  that  /devAmtt)  is  the  input  tile.  Ihe  information 
provided  to  the  user  comes  from  each  file  included  on  tape.  Included  are  the  maximum  and  minimum 
elevation  values  and  the  approximate  UIM  boundaries  of  each  file,  lire  program  assumes  unlabeled 
tapes  in  ASCII  format  with  no  header  or  trailer  files. 

SEE  ALSO 

g.region,  rn.dem.extr act,  m.examine.tape,  r. rescale,  r support 

AUTHOR 

Andrew  Heekin,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

ntdemextract  -  Extracts  USGS  Digital  Elevation  Model  (DEM)  data  from  half-inch  magnetic  tape. 
(GRASS  Data  Import  /Processing  Program) 

SYNOPSIS 

m.dem. extract 
m.dem.extract  help 

m.dem.extract  input  =name  output  ^name  blocksize  value 
DESCRIPTION 

m.dem.extract  extracts  USCiS  Digital  Elevation  Model  (DEM)  elevation  data  that  fits  into  the  user’s 
current  geographic  region  from  the  input  file  input,  in  Hocks  of  blocksize  bytes.  If  no  input  file  is 
specified  by  the  user,  input  is  taken  from  /dev/rmtO,  by  default.  Results  are  placed  in  the  named  output 
file,  and  stored  beneath  the  cell  directory  of  the  user’s  current  mapset.  mdem.extract  will  only  extract 
data  that  fall  within  the  boundaries  of  the  user’s  current  geographic  region.  Data  falling  outside  this 
region  will  be  ignored.  m.dem.extract  will  not  complain  if  the  input  file  does  not  cover  the  entire 
geographic  region.  The  program  assumes  unlalreled  tapes  in  ASCII  format  with  no  header  or  trailer 
files.  Ihe  user  should  run  m.dem.examine  prior  to  running  m.dem.extract  to  determine  the  size  of  the 
geographic  region  needed.  If  the  block  size  is  unknown,  run  the  command  nuexamine.tape. 

'Ihe  user  can  run  this  program  either  non-interactively  or  interactively.  The  program  will  be  run  notv 
interactively  if  the  user  specifies  program  arguments  on  the  command  line,  using  the  form: 

mdem.extract  input  =name  output  ^name  blocks* e=vo/ue 

Alternately,  the  user  can  simply  type  m.dem extract  on  the  command  line,  without  program 
arguments.  In  this  case,  the  user  will  be  prompted  for  needed  parameter  values  using  the  standard 
GRASS  interface  described  in  the  manual  entry  for  parser. 

Parameters: 

input  name  The  full  path  name  of  the  half-inch  tape  device  from  which  DEM  data  are  to  lx; 

extracted. 

Default:  /dev/rmtO 

output  name  Ihe  name  to  Ire  assigned  to  the  output  file  containing  raster  DEM  data  extracted 

from  half-inch  tape. 

blocksize  =value  The  physical  block  size  (record  length)  of  each  record,  in  bytes.  m.exanine.tape 
can  be  used  to  detennine  block  size. 

NOTES 

Ihe  user  should  check  the  boundaries  and  resolution  of  the  current  region  setting  (see  g.region) 
BEFORE  extracting  data,  since  m.dem.ex(ract  will  only  extract  the  data  that  falls  within  these 
boundaries  and  only  use  the  set  resolution  during  extraction. 

SEE  ALSO 

g.region,  m.dem.exanunc,  rn.exanune.tape,  r. rescale,  r. support  and  parser 
AUTHORS 

Andrew  iicckin,  U  S.  Army  Construction  Ejiginecring  Research  laboratory 

Improvements  to  | program  code  were  made  for  GRASS  4.0  by 
David  Satnik,  Central  Washington  University 
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NAME 

m.dmaUSGSread  -  txtracts  digital  terrain  elevation  data  (ITITD)  produced  by  the  Defense  Mapping 
Agency  (DMA)  but  supplied  by  the  USGS  (in  a  different  tape  format)  on  half-inch  magnetic  tape. 
(GRASS  Data  Import/Processing  Program) 

SYNOPSIS 

dd  [if  =tapedev]  ibs  =input-block-size  |  m.dmaUSGSread  top- value  bottom—  value  left  -value 
right  =value  output  name  logtil t=name 

DESCRIPTION 

m drna USGSread  extracts  digital  terrain  elevation  data  (DJTD)  tliat  was  produced  by  the  Defense 
Mapping  Agency  (DMA)  but  bought  from  the  USGS;  these  two  agencies  distribute  the  same  data  in 
slightly  different  tape  formats.  This  program  requires  the  use  of  the  UNIX  command  dd  to  read  the 
half-inch  magnetic  tape.  m.dmaUSGSread  should  be  ased  prior  to  using  the  GRASS  programs 
m.rot90  and  r.in.ll. 

Parameters  for  the  UNIX  dd  command  are  listed  below. 

if  =tapedev  I  he  path  name  of  the  tape  drive  from  w  hich  input  w  ill  be  taken  (usually 

/dev/rmtO). 

i  bs  =input -block-size 

lhe  physical  blocking  value  of  the  data  on  tape,  usually  written  on  the  tape  spool. 
If  this  value  is  unknown,  run  rn.examine.tape  prior  to  miming  nudmaUSGSread. 

Parameters  for  m.dmaUSGSread  are  listed  below. 

tap=value  Beginning  row  number  of  data. 

Optioas:  1-1201 

bottom—  value  1  aiding  row  number  of  data. 

Options:  1-1201 

left-value  Beginning  column  number  of  data. 

Options:  1-1201 

right  =value  I  aiding  column  number  of  data. 

Options:  1-1 20 1 

output  =name  Name  of  the  output  file  to  hold  the  extracted  DI  M  data, 

logfile  name  Name  of  a  file  to  hold  related  information  alxxit  the  extracted  data. 

EXAMPLE: 

I -or  example,  the  command: 

dd  if=/dcv/niil()  ibs =10240  |\ 

m.dmaUSGSread  top=l  bottom  =400  left  1  right  -500  \ 
output  =dcm  logfile=log 

will  extract  data  irom  /dev/rmtO  ;uid  put  the  first  4( M )  ruw  and  lust  5(Kt  columns  into  tin-  hie  deni 
located  in  the  user's  current  directory 

SEE  ALSO 

Options  for  Acquiring  Iteration  Data ,  by  Stuaii  Bradshaw  (AI)P  Report  N  .ST/22.  I  S AC  I  1*1  .  1 

DUD  and  DIM  I'levalion  I  kit  a  Ixlraciion .  bv  Stuart  Bradshaw,  Man  Martin,  and  (  bestir  kos 
(A DP  Report  N  SV22.  USA(  1  RI  .  P'.S.X), 

and  tin-  UNIX  inaniul  entn  for  dd 
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g.region,  nuked. examine,  m.dted.extract,  rn.examine.tape,  mregionJl,  m.rot90,  r. describe,  rJnJl, 
r. rescale,  rjlope.aspect 

AUTHORS 

James  Farley,  Arkansas  Archeological  Survey,  University  of  Arkansas 
Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

m.dtetLexanune  -  Provides  a  terse  description  of  level  1  and  2  digital  terrain  elevation  data  (DIED) 
files  produced  and  distributed  by  the  Defense  Mapping  Agency  (DMA)  on  half-inch  magnetic  tapes. 
(GRASS  Data  Import  /Processing  Program) 

SYNOPSIS 

m.dted .examine  [. tapedev } 

DESCRIPTION 

rn.dted.exam.ne  scans  digital  terrain  elevation  data  (DTED  -  Levels  1  and  2)  that  was  produced  and 
supplied  by  the  Defense  Mapping  Agency  (DMA)  on  half-inch  magnetic  tape  from  the  tape  device 
specified  by  tapedev ,  and  prints  to  the  screen  a  terse  description  of  each  file. 

If  the  user  specifies  no  tapedev  on  the  command  line  the  program  assumes  that  input  is  coming  from 
/dev/rmtO.  The  infonnation  provided  by  m.dted.examine  includes  the  UTM  borders,  cell  resolution, 
and  number  of  elevation  profiles  in  each  file. 

BUGS 

The  header  file  for  DTED  level  1  and  2  data  was  changed  in  1987.  m.dted.examine  and 
nudted.extract  operate  only  on  DIED  data  containing  pre-1987  headers.  DIED  data  containing  the 
pre-1987  headers  may  be  purchased  from  the  Defense  Mapping  Agency'  (DMA)  upon  request. 

SEE  ALSO 

Pursuance  of  Elevation  Data,  by  Stuart  Bradshaw,  USACERL 

DEM  and  DTED  I-levation  Extraction,  by  Stuart  Bradshaw,  Mary  Martin,  and  Chester  Kos, 
USACERL 

g.region,  m.dma USGSread,  m  dted.extract,  rn.examine.tape,  rn.region.il,  m.rot90,  r. describe, 
r.in.ll,  r. rescale,  r Mope. aspect 

AUTHORS 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
Andrew  Heekin,  U.S.  Army  Construction  Engineering  Research  laboratory 


r<> 


<  IRASS  4.0  (Summer  lu'M  ) 


U.S.  Anm  <  TUI 


m.dted.ex  tract 


GRASS  Reference  Maniutl 


m.dted.ex  tract 


NAMK 

m.dted.extract  -  1-xtracts  digital  terrain  elevation  data  (DUD  -  levels  1  and  2)  produced  and  supplied 
by  the  IXfense  Mapping  Agency  (IMA)  on  half-inch  magnetic  tapes. 

(GRASS  Data  Import  (Processing  Program) 

SYNOPSIS 

m.dted.extract  it=tapedev  of  ^  out  file  hf  =headjile  n  =)at  s=lat  e^lon  w  =lon 
DESCRIPTION 

nuke d.extr act  extracts  I  m  i )  (l  evels  1  and  2)  digital  terrain  elevation  data  produced  by  the  Defease 
Mapping  Agency  (DMA)  from  h;df-inch  magnetic  tapes  obtained  from  DMA  IDuta  is  read  from  the 
injxit  111*'  (if)  specified  by  tapedev.  11  the  user  docs  ix>t  specifv  anv  input  file  name  on  the  command 
line,  the  program  assumes  tlia'  in|xit  is  coming  from  /dev/rmtO.  Ilie  extracted  data  is  placed  in  the 
output  file  (of)  specified  by  outjile.  Ibis  program  slxxtkl  lx  used  in  conjunction  with  the  programs 
niropM)  ;uid  r.in.ll  to  convert  Dili)  data  to  GRASS  raster  format. 

if  Ilk-  pathname  of  the  tape  device  where  the  raw  DITJ)  data  exists  (default  is  /dev/rmtO) 

of  Ilk  full  pathname  of  the  output  file  into  which  the  extracted  tape  data  is  to  lx  copied 

hf  1  lie  full  pathname  of  a  file  to  contain  descriptive  information  about  the  extracted  data;  should  be 
placed  in  the  same  directory  as  the  ixitput  file 

n  North  latitude  value  defining  the  boundaries  of  the  extraction  geographic  region  (format: 
dd.mm.ss[n|s]) 

s  South  latitude  value  defining  the  extraction  geographic  region  (format:  ddmm.ss[n|s]) 

ea  1  ast  longitude  value  defining  the  extraction  geographic  region  (format:  ddmm_ss[e|w  ]) 

w  West  longitude  value  defining  the  extraction  geographic  region  (format:  dd.mm.ss[e|w]) 

Hie  n  s  e  jukI  w  parameters  define  a  geographic  region  that  should  completely  encompass  the  data  set. 
(kl.mm.ss  are  degree,  minute,  and  second  values.  Only  data  that  falls  within  this  defined  geographic 
region  v\  ill  lx  extracted  from  the  tape. 

EX  AMPLE 

Ilic  command  line: 

m.dted.extract  if~/devA-mtO  of-dted.out  hf  dtedJiead  n=37-30.00n  s=37.15.00n 
e=103J0.0Ow  w=103.45.00w 

will  extract  Dil  i )  data  from  /dev/rmtO,  store  it  in  a  file  named  died. out.  and  store  some  supporting 
infonnation  in  tlx  file  died.head.  Only  data  that  falls  within  the  geographic  region  defined  by  the 
coordinates  n,s,e  aixl  w  will  lx  extracted. 

NOTH 

'Ihc  usei  sh( xtld  examine  the  contents  of  the  header  file  produced  by  this  program;  it  contains 
infonnation  needed  as  inputs  to  the  data  rotation  and  raster  file  import  programs  m.rol90  ami  r.in.ll, 
respectfully. 

bugs 

lhe  fomiat  of  the  header  lile  for  DIIiD  Ixvcl  1  ;uid  2  data  was  chained  in  1987.  ntdled.extract  and 
rn.dted.examine  tally  operate  oil  DITJ)  data  containing  prc-1987  headers.  DTTD  data  containing  the 
prc-1987  headers  may  lx1  purchased  from  tlx  DMA  upon  request. 

DIAGNOSTICS 

Invalid  requests  are  so  designated. 

SEK  ALSO 

Pursuance  of  Elevation  Data,  by  Stuart  Bradshaw,  US ACER  I , 

DEM  and  DTEJ)  Elevation  Extraction,  bv  .Stuart  Bradshaw,  Marv  Martin,  ;uid  Chester  Kos, 
USACJ-RI, 
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g. region,  m.dmaUSGSread,  m.dted.examine,  nuexanune.iape,  m.region.ll,  m.rot()0,  r.descnbe, 
r.in.ll,  r. rescale,  r  Mope  .aspect 

AUTHOR 

Michael  Shapiro.  U.S.  Anns  Construction  I-Jigincering  Research  laboratory 
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NAME 

rn.examne.tape  -  Provides  a  description  of  the  files  on  half-inch  magnetic  tape. 

(GRASS  File  Management  Tool) 

SYNOPSIS 

mxxamine.tape 

DESCRIPTION 

nuex andne.tape  is  a  convenient  tool  for  previewing  a  tape  and  obtaining  block  size  values.  After  the 
user  enters  the  command 

rn.examine.tape 

the  program  will  prompt  the  user  for  the  full  path  name  of  the  tape  device  on  which  the  tape  is 
mounted.  In  most  cases,  this  will  be  Alev/rmtO.  However,  the  user  must  enter  this,  as  there  is  no 
default  value  for  the  tape  device  name.  The  user  is  then  prompted  to  enter  the  buffer  size  to  be  used 
when  reading  the  tape.  Tne  buffer  size  is  the  amount  of  memory  allocated  to  read  one  physical  record 
of  the  tape.  If  the  user  hits  RETURN,  the  program  will  assume  a  default  buffer  size  of  32767  bytes. 

m.examine.tape  reads  the  tape  specified  by  the  user  and  reports  back  the  block  size  (record  length)  and 
the  number  of  blocks  for  each  file  contained  on  the  tape,  ntexamine.tape  can  be  used  on  any  half¬ 
inch  magnetic  tape.  'Ihe  user  has  the  option  of  sending  the  output  into  a  file  or  viewing  the  output  on 
the  terminal  screen. 

NOTES 

The  Ixiffer  size  is  the  anwxmt  of  memory  allocated  to  read  one  physical  record  on  the  tape.  Magnetic 
tape  devices  will  accept  a  request  to  read  more  bytes  than  actually  exist  in  any  given  record  on  a  tape. 
However,  m. examine. tape  reads  only  as  many  bytes  as  physically  exist  on  the  tape  and  returns  the 
number  of  bytes  actually  read.  The  user  is  allowed  to  alter  the  buffer  size  in  order  to  request  smaller 
reads  for  tape  devices  unable  to  handle  requests  this  large  (32767  bytes),  or  to  request  larger  reads  for 
tapes  with  larger  record  sizes  read  on  drives  able  to  handle  larger  record  sizes. 

Note  that  rn.examine.tape  cannot  be  used  to  examine  the  content  of  either  ordinary  files  or  one- 
quarter-inch  tape  cartridges. 

SEE  ALSO 

m.dem.examine,  rn.dem.extr act,  rndma  USGSread,  mdtedexamine,  melted. extract,  mlulc.USGS, 
rn.lulc.read 

AUTHOR 

Michael  Shapiro,  UT  Army  Construction  ">v  "'leering  Research  laboratory 
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NAME 

nujlip  -  Flips  elevation  data  extracted  from  systems  that  retrieve  ilata  (a  rows  from  south  to  north. 
(GRASS  Data  Import/Processing  Program ) 

SYNOPSIS 

mJlip 
milip  help 

m.flip  [-qj  input -name  output  =name  raws— value  cols  =value  bpc  =value 
DESCRIPTION 

nujlip  is  similar  to  nurot90.  I  low  ever,  rather  than  rotating  a  raster  file,  nujlip  Hips  the  contents  of  the 
raster  generated  by  tape  extraction  programs  alxxit  the  east-west  axis.  Hipping  may  be  necessary  to 
compensate  for  the  orientation  of  the  data  read  from  tape.  This  program  can  Ire  used  in  conjunction 
with  the  program  r.in.ll  to  convert  this  rotated  data  into  GRASS  raster  format. 

nujlip  requires  five  inputs  to  be  entered  by  the  user.  These  parameters  and  the  optional  fl;ig  setting  are 
described  Mow . 


Flag: 

-q 

Parameters: 
input  —name 
output  name 
rows— value 
ceAs  =value 

bpc  -value 


Run  quietly,  suppressing  output  of  messages  on  program  progress  to  standard 
output. 

The  full  pathname  of  at  existing  file  containing  the  data  to  be  flipped. 

The  full  pathname  of  the  output  file  in  which  the  rotated  data  are  to  lx:  stored. 

The  number  of  rows  of  data  in  the  input  file.  Values  must  lie  positive  integers. 

Ihe  muni  -cr  of  columns  of  data  in  the  input  file.  Values  must  lx*  positive 
integers. 

Ihe  numlx'r  of  bytes  per  cell  (i.c.,  per  data  value)  in  the  input  file.  Values  must 
be  positive  integers. 


EXAMPLE 

The  following  command: 

mJlip  input  =AmpAoo.out  output—  AmpAlip.out  rows  301  cols-358  bpc=2 

will  rotate  t.  .  mp/foo.out,  and  place  the  rotated  file  in  /tmp/flip.out.  Here,  tlx  input  file  is  301 
row  s  by  358  columns,  at  2  bytes  per  data  value. 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  sre  alpha  director,  and  must  lx-  compiled 
separately  by  the  user. 


SEE  ALSO 

Pursuance  of  Idevation  Data ,  I  tv  Stuart  Bradshaw,  USAOtRI. 

DIM  and  D'lT'J)  lievation  Extraction,  bv  Stuart  Bradshaw,  M;trv  Martin,  and  Chester  Kos, 
USACURl. 


g. region,  m.dmaUSGSread,  nudted.examine,  m.dted.extruct,  mexanune.tape,  nuregion.il ,  m.rot90, 
r.  describe,  r.in.ll,  r.  rescale,  r. slope. aspect 

AUTHORS 

Donald  Newcomb,  U.S.  Naval  Oceanographic  Office, 

borrowing  heavily  from  the  nurolQO  program  written  ly  Michael  Shapiro,  IJ.S.  Anns  C  onstruction 
1 -ng  i  nee  ring  Research  laboratory 
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NAME 

m.gc2ll  -  Converts  geocentric  to  geographic  coordinates. 

(GRASS  Data  Inport/Processing  Program) 

SYNOPSIS 

m.gc211  x=#y=#z=#s  =spheroid 
DESCRIPTION 

m.gc2ll  returns  geographic  coordinates  for  geocentric  ones  supplied  by  the  user.  It  performs  the 
reverse  operation  of  the  GRASS  program  m.U2gc.  The  x,  y  and  z  values  are  the  three  dimensions 
needed  to  locate  a  point  in  three- dim'"  sional  space.  The  values  that  are  printed  include  the  latitude, 
the  longitude  and  the  height  above  (or  distance  below)  the  spheroid. 

The  list  of  spheroids  available  is  somewhat  dynamic.  It  may  not  contain  exactly  the  ones  listed  below. 
To  determine  the  current  list  of  possible  spheroids,  simply  type  in: 

m.gc211  x  =0  y  =0  z  =0  s=help 

A  list  of  available  spheroids  will  be  printed  on  the  screen.  If  the  spheroid  desired  is  not  on  the  list,  the 
values  for  the  semi-major  axis  and  the  eccentricity  squared  for  the  spheroid  may  be  entered  in  place  of 
a  spheroid  name  in  the  following  format: 

s  =a  =serri -major _axis  ,e  =eccentri  city_squared 

SOME  POSSIBLE  SPHEROIDS 

(The  on-line  listing  includes  only  the  spheroid  names ) 


Spheroid 

Commonly  used  for 

Semi-major  axis 

EccentridtY  sqrd 

australian 

Australia 

6378160.0 

0.0066945419 

bessel 

Japan 

6377739.155 

0.0066743722 

clark66 

N.  America 

6378206.4 

0.006768658 

clark8Q 

France,  Africa 

6378249.145 

0.0068035113 

everest 

India,  Bunna 

6377276345 

0.0066378466 

international 

Europe 

6378388.0 

0.00672267 

wgs72 

worldwide  ewerage 

6378135.0 

0.006694317778 

EXAMPLE 

ra.gc2ll  x  =0.0  y  =0.0  z  =6356750.520017  s=wgs72 

Results: 

lat  =90N 

lon=90W 

h=0.0000 


NOTES 

Bor  a  brief  discussion  of  spheroids  see  mll2u. 

Bor  a  brief  discussion  of  geocentric  coordinates  see  m.ll2gc. 

This  is  an  experimental  program.  It  is  part  of  an  initial  effort  to  incorporate  geographic  coordinates 
into  GRASS. 

SEE  ALSO 

nudatumshift,  m.lI2g<  ,  m.ll2u,  m.u2ll 

AUTHOR 

Michael  Sliapiro,  U  S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

m.U2gc  -  Converts  geograpliic  coordinates  to  geocentric  coordinates. 

(GRASS  Etata  ImporbProcessing  Program) 

SYNOPSIS 

mJI2gc  lat  =ddjrtnuss{n |  j}  lan=dd.rmuss{e\w}  [h=height]  s=spheroid 
DESCRIPTION 

m.U2gc  returns  geocentric  coordinates  for  geographic  coordinates  (latitude  and  longitude).  Geographic 
coordinates  are  in  degrees,  minutes,  and  seconds  and  must  include  designation  of  north  or  south  {n|s} 
and  east  ex-  west  {e|w}.  The  spheroid  on  which  they  are  based  must  also  be  entered.  The  height  (in 
meters)  above  the  spheroid  is  optional. 

The  list  of  spheroids  available  is  somewhat  dynamic.  It  may  not  contain  exactly  the  ones  listed  below. 
To  determine  the  current  list  of  possible  spheroids,  type  in: 

m.U2gc  lat=On  lon=Ow  s=help 

A  list  of  available  spheroids  will  be  printed  on  the  screen.  If  the  spheroid  desired  is  not  on  the  list,  the 
values  for  the  semi- major  axis  and  the  eccentricity  squared  for  the  spheroid  may  be  entered  in  place  of 
a  spheroid  name  in  the  following  format: 

s  =a  senu  -major  uaxis  ,e  =eccentricity  squared 

SOME  POSSIBIT.  SPHEROIDS 

(The  on-line  listing  includes  only  the  spheroid  names) 


Spheroid 

Commonly  used  for: 

Semi-major  axis 

Eccentricity  sqrd 

australian 

Australia 

6378160.0 

0.0066945419 

bessel 

Japan 

637773s.  155 

0.0066743722 

clark66 

N.  America 

!  6378206.4 

0.006768658 

cl  ark  .SO 

Irance,  Africa 

6378249.145 

0.00680351 13 

cv  crest 

India,  Bunna 

637727634  5 

0.0066378466 

international 

Europe 

6378388.0 

0.00672267 

wgs72 

worldwide  coverage 

6378135.0 

:  0.0066943177~8 

EXAMPLE 

mJI2gc  lat  -  On  Ion  90 w  s=wgs72 

Results: 
x  =0.0 

y  =6378135.0 
/=().() 

The  distances  designated  bv  "x."  ”v,"  and  "/"  are  in  meters  from  the  center  of  the  earth.  Because 
the  sample  pxnf  is  on  the  equator  and  is  at  '>n  degrees  west,  two  ol  tin  three  parameters  haw  a 
v  alue  of  zero  (i.e.,  the  point  is  at  the  origin  of  those  two  dimensions). 

NOTES 

lor  a  brief  discussion  e>l  sphewids  see  8; 

f  xwiaphic  cixudi  nates  il.itianh  -1< i«iltt>l  i  des.iiiv  the  hx-ation  a  point  the  <  ami  n  iative  :  th. 
equator  in  th'  noitli/south  directioie  an> '  t*  iatr.  <  to  (  neeitu  ich  m  the  east-'w  rst  viimtions  llu-  .  u  n- 
p  "'it  'A  ill  ha',  e  di  1 1  ere!  it  i  .  >  •  ;  dinati  s  li. *  1 |.  line  U  11  >>  ,  hen  'id  'a  ■  :  a\  the  ,.npi.  siin.it  on  oi  t  Ik  s'li  V 

ot  ill;  e.ulii.  Hi.  gei  s'.,  an  u  eootdm.i'.  :u\  a  lie?  -lesi  tilx  tin  punt  ■■..  the  basis  o|  the  > 
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center  of  the  earth,  which  is  why  they  are  called  "geocentric."  Describing  the  location  of  a  point  in  a 
spheroid  requires  three  paints:  x,  y,  and  z;  these  are  measured  out  from  the  center  along  three  different 
axes.  The  distances  given  are  in  meters. 

This  is  an  experimental  program.  It  is  part  of  initial  efforts  to  incorporate  geographic  coordinates  into 
GRASS. 

SEE  ALSO 

mdatunuhift,  m.gc2ll,  m.ll2u,  m.u2ll 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

null2u  -  Converts  geographic  coordinates  to  Universal  Transverse  Mercator  (UTM)  coordinates. 
(GRASS  Data  Import/Processing  Program) 

SYNOPSIS 

mJ12u 
mJ12u  help 

mJ12u  [-rwozj  spheroid  =name  [zoo t=value\  [input  =name]  [output  =name] 

DESCRIPTION 

m.U2u  converts  geographic  coordinates  (i.e.,  latitudes  and  longitudes)  to  Universal  Transverse  Mercator 
(UIM)  eastings  and  northings.  The  user  must  specify  the  spheroid  on  which  to  base  the  UTM 
conversion.  The  user  may  optionally  specif)'  the  UTM  zone;  however,  the  program  c;tn  detemiine  this 
from  the  geographic  coordinates  submittal. 

The  list  of  spheroids  available  is  somewhat  dynamic.  At  the  time  of  this  release,  available  spheroids 
included:  aiiy,  australian,  bessel,  clark66,  everest,  grsSO,  hayford,  international,  krasovsky,  wgs66, 
wgs72,  and  wgs84  (see  table  below). 

This  command  can  lie  run  either  non- interactively  or  interactively.  The  user  can  run  the  program  non- 
interactively  by  entering  desired  flag  settings  and  parameter  values  on  the  command  line  using  the 
following  format: 

m J12u  [-rwoz]  spheroid  =name  ixtne  value)  [input  —name)  [ output  name) 

Alternately,  the  user  can  simply  type: 

mJ12u 

on  the  command  line.  In  this  case,  the  user  will  be  prompted  for  parameter  values  and  flag  settings 
through  the  standard  interface  described  in  the  manual  entry  for  parser. 

Input  can  be  entered  from  the  keylxard  or  from  tut  input  file.  In  either  case,  input  should  lx*  entered 
with  one  longitude  and  latitude  pair  per  line,  in  the  form: 

degrees:minutes:seco!Kls{  1  j\V)  dcgrees:niinutcs:scconds{N |S} 
degrees:minutes:seconds{  1  [W  }  degrees:minutes:seconds{N[S} 
degrees: mi nu tes:sec< )nds{ I  ,[\V}  dee rees.minutcs :seconds{N |S} 
degrces:niinuies:seconds{l  i|W)  degrees  :nii  nutes : seconds{N  |S} 

end 

If  the  user  sets  the  r  fktg,  rrulllu  will  exjvct  the  order  of  the  eoenlinatcs  to  Iv  reversed.  and  stated  as 
latitude,  longitude  jrairs,  rather  ilian  as  longitude.  latitude  pmrs. 

Similarh  .  the  user  can  elect  t>  •  send  ixilput  to  an  output  tile  or  !b\  d  I, min  tn  si.mdird  <>ut|Xtl  (tile 
user's  terminal  scneiii.  II  the  iihi  sits  itu  w  flag.  output  will  lx-  printed  m  a  lotmai  mitable  lor  ui|xit 
to  programs  like  d.potnis.  Txample  input  mid  out|xit  an  shown  N  low  ts< 1  _\  Wll‘1  I  >. 

l*ngram  llag 

Flags: 

-r 

-H 

-O 

-/ 
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Parameters: 
spheroid  =name 


zone  =value 


input  name 


Reference  spheroid  (ellipsoid). 

Options:  airy,  australian,  bessel,  clark66,  everest,  grs80,  hayford,  international, 
krasovsky,  wgs66,  wgs72,  wgs84 

UTM  zone  number  (results  will  be  forced  into  this  UTM  zone). 

Options:  1-60 

Name  of  an  existing  input  file  containing  longitude,  latitude  coordinates  to  be 
converted. 


output  -  name  Name  to  be  assigned  to  the  output  file  containing  UTM  coordinates  and  zone 
designations. 


AVAILABLE  SPHEROIDS 

(The  on-line  listing  includes  only  the  spheroid  names) 


Splteroid: 

Semi-major  axis 
(Equatorial  Radius)  (a): 

Eccentricity  sqrd  (e),  Flattening  (f), 
or  Polar  Radius  (b): 

Commonly  used  for: 

airy 

a  =637 7563  3% 

e =.006670540 

australian 

a=6378160 

f =1/298 35 

Australia 

bessel 

a=6377397.155 

e=D06674372 

Japan 

claik66 

a=6378206.4 

b=63565836 

N.  America 

everest 

a=6377276345 

e=D066378466 

India,  Burma 

grs80 

a=6378137 

f =1/298  357 

hayford 

a=6378388 

f =1/297 

international 

a=6378388 

f =1/297 

Europe 

krasovsky 

a=6378245 

f=l/2983 

wgs66 

a=6378145 

f=l/29835 

worldwide  coverage 

wgs72 

a=6378135 

f =1/298 36 

worldwide  coverage 

wgs84 

a=6378137 

f =1/298 357223563 

worldwide  coverage 

EXAMPLE 

Assume  the  user  has  input  the  command: 

mJI2u  spheroid  =wgs72  input  =41  Jnftle  ontpnt=utm^mtflle 

where  the  input  file  ILinfile  contains  the  following  longitude,  latitude  values: 

155 ‘.30:00 W  19:35  DON 
16530D0W  19:35 DON 
14530D0W  20D0D0N 
13530D0W  21D0D0N 
end 


Output  would  then  be  sent  to  the  output  file  utnuoutfile ,  containing  the  below  Easting  and  Northing 
coordinate  values  and  UTM  zone  designations: 

237740.8527081 8  2167292.1076231  5 
44756064349407  2165450.19058336  3 
65692161734802  2212183.40032627  6 
448035.11644906  23222283038167  8 
end 


NOTES 

Spheroids,  the  solids  associated  with  an  ellipse,  are  also  known  as  ellipsoids.  They  are  used  as  the  best 
possible  model  to  simulate  the  shape  of  the  earth  with  its  flattened  poles  and  bulging  equator.  They  are 
the  mathematical  means  for  establishing  control  points  to  use  as  a  reference  when  determining  exact 
locations  on  the  earth.  A  cohesive  set  of  these  control  points  is  called  a  datum. 
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The  spheroids  listed  above  have  been  used  as  the  basis  for  a  number  of  different  datums.  The  North 
American  Datum  of  1927  (NAD  27)  was  based  on  the  Clark  1866  ("clark66")  spheroid.  This  was  a 
recent  current  standard  datum  for  North  America.  Be  aware,  however,  that  a  new  datum,  NAD  83,  has 
been  developed  using  the  Geodetic  Reference  System  1980  spheroid;  this  is  now  available  in  m.ll2u  as 
the  Mgrs80”  spheroid.  The  "wgs66",  "wgs72",  and  "wgs84"  spheroids  are  for  worldwide  use.  The 
"wgs72"  spheroid  has  been  used  fairly  widely  by  the  Department  of  Defense  (DUD)  and  is  the  basis  for 
the  World  Geodetic  System  1972  datum.  This  datum  has  also  been  recently  replaced;  the  new  DOD 
datum  is  WGS  84  (wgs84).  Both  datums  are  available  within  m.ll2u. 

To  use  spheroids  other  than  those  listed  here,  the  user  can  add  lines  to  the  ellipsoid  parameter  definition 
file  in  SGISBASFVetc/ellipse.table. 

Read  the  marginalia  of  your  source  map  to  determine  which  spheroid  was  used  to  produce  the  map  on 
which  you  are  working. 

This  program  has  received  only  limited  testing.  It  should  be  used  with  some  caution. 

FILES 

See  ellipsoid  parameter  definition  file  in  $GISBASE/etc/ellipse.table. 

SEE  ALSO 

For  australian,  ciark66,  grs80,  hay  ford,  international,  krasovsky,  and  wgs72  ellipsoid  parameters,  see: 
John  P.  Snyder,  Map  Projections  -  A  Working  Manual,  U  S.  Government  Printing  Office, 
Washington  DC,  1989.  U.S.  Geological  Survey  Professional  Paper  1395;  from  Table  1,  p.12. 

For  bessel,  aity,  everest,  and  vvgs66  ellipsoid  parameter  values,  see: 

Thomas  O.  Seppelin,  The  Department  of  Defense  World  Geodetic  System  1972,  presented  at  the 
International  Symposium  on  Problems  Related  to  the  Redefinition  of  North  American  Geodetic 
Networks,  Fredericton,  New  Brunswick,  Canada  in  May,  1974;  see  Table  9.  p35. 

For  wgs84  parameter  values,  see: 

U.S.  Naval  Oceanographic  Labs. 

Also  read  GRASS  User’s  Reference  Manual  entries  for: 

d.labels,  d.points,  d.sites,  d. where,  nudatunushift,  m.gc2ll,  m.ll2gc,  m.u2ll,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Fngineering  Research  laboratory 
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NAME 

m.luic.USGS  -  Creates  raster  map  layers  from  a  Composite  Theme  Grid  (CIX3)  file  created  by 
rn.lulc.rcad.  rn.lulc.read  extracts  the  CFG  data  from  an  ASCII  landuseAandcover  (lulc)  CFG  format 
file  supplied  by  the  USGS. 

(GRASS  Data  Import  /Processing  Program) 

SYNOPSIS 

mJulc.USGS  input_file 

DESCRIPTION 

rn.lulc.USGS  creates  the  following  raster  map  layers  from  the  CFG  file  created  by  rn.lulc.read,  and 
places  them  into  the  user’s  current  mapset: 

1.  Land  Use  &  Land  Cover 

2.  Political  Units 

3.  Census  Units 

4.  Hydrologic  Units 

5.  Federal  Land  Ownership 

6.  State  Land  CXvnership. 

Since  the  CFG  file  nay  not  contain  all  of  layers  listed  above,  mJulc.USGS  will  extract  only  the  raster 
map  layers  that  exist  in  the  CFG  file. 

The  CFG  file  contains  all  of  the  geographic  region  definition  information  necessary  for  creating  the 
raster  map  layers,  including: 

1.  Grid  Zone 

2.  Projection  Type  (UTM) 

3.  Cell  Resolution  (ew_res  =  nw_res) 

4.  Multi-byte  data  formation 

5.  Geographic  region  coordinates. 

rn.lulc.USGS  will  use  the  geographic  region  information  definition  supplied  with  the  CFG  file  and  NOT 
the  geographic  region  definition  currently  set  for  the  user’s  mapset;  (note  that  this  is  different  than  is 
the  case  with  many  of  the  other  GRASS  map  development  commands). 

When  m.lulc.USGS  is  executed,  it  will  check  the  file  for  a  specified  layer  and  then  ask  the  user  if  he 
wishes  to  extract  the  associated  raster  map  layer.  The  user  is  then  prompted  for  the  name  of  a  new 
raster  file  in  which  output  is  to  be  placed.  rn.lulc.USGS  will  then  create  this  raster  file  and  all 
supporting  (eg.,  category,  cell  header,  color  table,  etc.)  files. 

EXAMPLE 

In  the  example  below ,  raster  data  is  extracted  from  a  CFG  file  (named  lulc)  that  contains  only  LAND 
USE/I  AND  COVER  data: 

mJulc.USGS  lulc 

MAP  TH  U  .:  IX)1X3E  CTTY,  KS  1:250,000  LU,  PB,  CN,  HU,  FO 
The  Composite  Theme  Grid  file  contains  <1  >overlays 
and  has  a  map  axle  type  of  <01  > 

D>  you  Wish  to  Ocate  <  LAND  USE/LAND  OOVER  >  Raster  File  (yin)  [y]  y 

Enter  File  Name  for  LAND  USE/LAND  COVER  O/erlay 
Enter  ’list’  for  a  list  of  existing  raster  files 
Hit  RE1URN  to  cancel  request 

>  I  and  use 
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Creating  <ianduse>from  <LAND  USE/LAND  COVER  > Overlay:  95% 

Number  of  Categories:  76  (UNLABELED) 

Writing  Cell  Header  Information 
Writing  Color  Table  Information 

Conversion  is  Complete 

BUGS 

tn.lulc.USGS  does  not  currently  extract  Census  unit  data.  Also,  only  the  cataloging  unit  is  extracted 
from  the  CTG  file  (see  the  Land  Use  and  land  Cover  Data  User’s  Guide  supplied  by  the  USGS). 

SEE  ALSO 

USGS  Land  Use  and  Land  Cover  Data  User’s  Guide 
g.region,  rn.lulc.read 
AUTHOR 

Kenneth  Shepardson 

Specfrum  Sciences  &  Software,  Inc. 

(904)  862-3031 
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NAME 

rn.lulc.read  -  Extracts  Landuse/Landcwer  data  in  die  ASCII  Composite  Theme  Grid  (CTG)  data 
format  distributed  by  the  USGS  in  to  a  working  file  for  rn.lulc.USGS. 

(GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

dd  [if  =t  ape  dev]  ibs=input  block_size  cbs  =80  coov  =unblock  \  mJulc-read  argl 
DESCRIPTION 

rn.lulc.read  extracts  USGS  Land  Use/Land  Cover  data  distributed  in  the  ASCII  CTG  format.  Extracted 
data  is  placed  into  a  file  specified  by  argl.  m.lulc.read  should  be  used  prior  to  using  the  GRASS 
program  rn.lulc.USGS. 

rn.lulc.read  reads  the  data  from  standard  input,  allowing  the  user  to  pipe  in  the  data  from  a  file. 

Data  can  also  be  read  directly  from  the  half-inch  magnetic  tape  distributed  by  USGS,  by  using  the 
UNIX  command  dd. 

Parameters: 

if  =4apedev 

the  pathname  of  the  input  tape  drive  (usually  /devA*mtO) 
ibs=input 

the  physical  Mocking  value  of  the  data  on  tape,  usually  written  on  the  tape  spool.  If  this  value 
is  unknown,  run  m.examine .tape  prior  to  mJulc.read. 

cbs  this  is  the  conversion  blocking  factor  for  ASCII  CTG  file  and  is  by  default  set  to  80. 

cone  set  conv  to  unblock  when  extracting  ASCII  C1G  data 

argl  the  name  of  the  output  file  where  the  data  will  be  stored  in  binary  formal. 

EXAMPLES 

READING  FROM  A  FILE: 

mJulcxcad  outfile  <  infile 

The  above  command  will  read  the  data  from  infile  and  place  the  results  into  outfile.  Note  that  infile 
must  be  extracted  from  the  USGS  CTG  half-inch  magnetic  tape  using  the  UNIX  dd  command: 

dd  if=/devA'mtO  of=infiIe  ibs=32000  cbs  =80  conv  -  unblock 

READING  DIRECTLY  IROM  HALF-INCH  MAGNETIC  TAPE: 

dd  if=/devA-mtO  ibs  =32000  cbs  =80  conv— unblock  |  mJulcjread  outfile 

The  above  command  will  extract  data  with  a  blocksize  of  32000  from  /dev/rmtO,  and  put  the  results  in 
the  file  outfile. 

SEE  ALSO 

UNIX  ntanual  entry  for  dd 
rn.examine.tape,  rn.lulc.USGS 

AUTHOR 

Kenneth  Shcpardson 

Spectmm  Sciences  St  Software,  Inc. 

(904)  862-3031 
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NAME 

nuregion.ll  -  Converts  Universal  Transverse  Mercator  (UTM)  coordinates  falling  within  the  current 
geographic  region  from  UTM  coordinates  to  geographic  (latitude/longitude)  coordinates. 

(GRASS  Data  Import/Processing) 

SYNOPSIS 

nuegionJl 
mjregioaJl  help 
nucgianJI  spheroid  =name 

DESCRIPTION 

rn.region.il  takes  current  geographic  region  settings  in  UTM  coordinates,  and  converts  them  to 
geographic  coordinates  (i.e.,  latitudes  and  longitudes).  It  also  prints  the  length  (in  meters)  of  one  arc- 
second  at  each  of  the  four  edges  of  the  geographic  region.  The  user  must  enter  the  spheroid  upon 
which  to  base  the  geographic  coordinates. 

The  list  of  spheroids  available  is  somewhat  dynamic.  It  may  not  contain  exactly  the  ones  listed  below. 
To  determine  the  current  list  of  possible  spheroids,  simply  type  in: 

nuegiaoJl  help 

A  list  of  available  spheroids  will  be  printed  on  the  screen. 

AVAILABLE  SPHEROIDS 

(The  on-line  listing  includes  only  the  spheroid  names.) 


Spheroid: 

Semi-major  axis 
(Equatorial  Radius) 
(a): 

Eccentricity  sqrd  (e), 
flattening  (f), 
or  Polar  Radius  (b): 

Commonly  used  for: 

airy 

a=6377563.396 

e  =.006670540 

australian 

a=6378160 

f =1/298. 25 

Australia 

bessel 

a=6377397.l55 

e =.006674372 

Japan 

clark66 

a=6378206.4 

b  =6356583 .8 

N.  America 

everest 

a  =6377276.345 

e =.0066378466 

India,  Bunna 

grs80 

a  =6378137 

1=1/298.257 

hayford 

a =6378388 

f =1/297 

international 

a  =637 8388 

f =1/297 

Europe 

krasovsky 

a  =6378245 

f =1/298  .3 

wgs66 

a  =6378145 

f =1/298. 25 

worldwide  coverage 

wgs72 

a  =6378 135 

f =1/298  26 

worldw  ide  coverage 

wgs84 

a  =63781 37 

1=1/298.257223563 

worldwide  coverage 

EXAMPLE 


mj-egiunJI  spheroid  =dark66 

Results: 


WINDOW 

4928000.00N 

609000 .00 E  /.ONI 

491 4000 .00S 

590000 .00 W 

4430.06N 

44 .29 .5 7 N 

103  32.04  W 

1 03 .37 .44 W 

44.2232N 

44.22.23N 

1 03  32. 13 W 

1 03 .37 .55' W 

At  northern  edge  1  arc  second  longitude  =22. 088500m 
At  soutliem  edge  1  arc  second  longitude  22.135998m 
At  western  eck;e  1  arc  second  latitude=30.860285m 
At  eastern  edge  I  arc  second  latitude  =30 ,863082m 


IMP 
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The  values  for  the  geographic  coordinates  are  rounded  to  the  nearest  second  in  this  example.  They  would  be 
more  precise  in  die  actual  output  that  is  printed  on  the  screen. 

SEE  ALSO 

nudatunushift,  m.ll2u,  m.u2ll,  r.inJI 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

m.rot90  -  Rotates  elevation  data  extracted  by  either  nudted.extract  or  m.dmaUSGSread 
(GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

m  j-ot90 
m  .rot 90  help 

in  .rot  90  [-q]  input-name  output -name  rows=value  ceis=value  bp c=value 
DESCRIPTION 

nurot90  is  used  as  a  companion  program  to  the  HTH)  aixl  D1A1  digital  elev  ation  data  tajx  extraction 
programs  rrulted. extract  and  m.dmaUSGSread .  m.  rot  9  3  rotates  the  contents  of  the  out|iut  hies 
generated  by  these  tajv  extraction  programs  90  degrees.  Rotation  is  necessary  to  compensate  for  the 
orientation  of  the  data  read  from  tape,  'lhis  pregram  can  be  used  in  conjunction  with  the  program 
r.in.ll  to  convert  this  rotated  data  into  GRASS  raster  map  layer  form. 

m.rot90  req.iires  five  inputs  to  lie  entered  by  the  user.  These  parameters  and  the  optional  flag  setting 
are  described  below. 

Flags: 

-q 

Parameters: 
input  =name 

output  -name 

rows  -value 
vvis  =value 
bpc  =value 

EXAMPLE 

'Ihe  following  command: 

m.rot90  input  Amp/dma. out  output  =AmpAot. out  rows-301  cols  -35S  bpc  2 

will  rotate  the  file  /Unp/dma.txit,  ;uid  place  the  rotated  file  in  /tmp/rot.mt.  Here,  the  input  file  is  301 
rows  by  35X  columns,  at  2  bytes  jter  data  value. 

NOTES 

'Ihe  user  should  note  that  since  the  output  file  is  rotated  “0  degrees  trout  the  nririita!  intni!  tile,  the 
rows  and  columns  have  I  teen  interchanged.  Hence,  in  the  altovc  example,  the  numlvt  "I  (301, 
and  columns  (33 .s’)  stated  by  the  user  on  tin-  command  litre  were  tltose  present  in  the  input  lile  Ihe 
output  file,  however,  will  have  35S  rows  and  301  columns. 

SEE  ALSO 

Pursuance  of  l/evaiion  Data,  oy  Stuart  Bradshaw  .  I  S At  I  Rl. 

D/’M  and  Dll-.l)  l/evation  I'xlraction.  In  Stuart  Bradshaw .  Man  M.aun.  and  <  it.  Met  K< 
USACIRI 

g. region,  m.dmaUSGSread,  nutted. examine ,  m  ilted  extract,  m.exanune .tape .  nt.fhp.  m  r,  eutn.il. 
r.  describe,  r.in.ll,  r. rescale,  r. slope  .aspect 

AUTHOR 

Michael  Shapiro  l  \S.  Amy  (dnstnution  1  tie  meeting.  Reseat  eh  l.ilxtralon 


14m  quietly,  suppressing  output  of  messages  on  program  progress  to  standard 
output. 

Ihe  full  pathname  of  an  already  existing  file  containing  the  data  to  be  rotated. 
Ibis  input  file  is  usually  the  output  file  created  by  m.dted.exlract  or 
nudma  USGSread. 

Name  to  be  assigned  to  the  resultant,  rotated  output  file.  Ihe  full  pathname  of  the 
output  file  in  w  hich  the  rotated  data  ;tre  to  Ite  stored. 

Ihe  number  of  rows  of  data  in  the  input  file. 

Ihe  nun  titer  of  columns  of  data  in  the  input  liie. 

Ihe  number  ol  bytes  per  cell  in  the  input  file. 
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NAME 

mtigersegion  -  Finds  geographic  region  information  for  U.S.  Census  Bureau  TIGER  input  data. 
(GRASS  Data  Import  /Processing  Program) 

SYNOPSIS 

in  .tiger  .region 
m  .tiger .region  help 

miiger  .region  infile  name  /zoo  e=value]  [spheroid  =name] 

DESCRIPTION 

m. tiger. region  is  a  program  designed  to  evaluate  a  file  of  raw  type  1  Census  (TIGER)  data  and 
determine  the  geographic  region  covered  by  that  input  file.  Output  is  sent  to  standard  out,  and  gives  the 
east,  west,  north,  and  south  boundaries  for  the  given  input  data  file. 

If  the  user  specifies  the  input  file  name  and  (optionally)  the  zone  number  or  spheroid  to  be  used  on  the 
command  line,  the  program  will  run  non-interactively;  if  no  zone  number  or  spheroid  name  is  given,  the 
default(s)  will  be  used  (see  below).  Alternately,  die  user  may  simply  type  nuiger. region  on  the 
command  line;  in  this  case,  the  program  will  prompt  the  user  for  parameter  values  using  the  standard 
GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

COMMAND  LINE  OPTIONS 
Parameters: 

infile=rrame  Input  file  name  in  which  raw  TIGER  data  (type  1)  are  stored. 

zon t=value  Universal  Transverse  Mercator  (UTM)  zone  for  this  county. 

Options:  -60  -  60 
Default:  0 

spheroid  =name  Name  of  spheroid  to  be  teed. 

Default:  clark66 

Available  spheroids  are: 

australian 

bessd 

clark66 

clark80 

everest 

international 

wgs72 

wgs84 

It  is  recommended  that  the  user  choose  the  clark66  (default)  spheroid  when 
dealing  with  TIGER  data  as  it  is  the  most  consistent  with  the  original  data. 


EXAMPLES 

If  the  user  typed  simply: 

m .tiger .region  infile  Hnputfileruune 

program  output  would  look  similar  to  this: 

Number  of  calculated  zones  is:  2 

INFO  FOR  ZONE  1: 

zone  number:  13 

percentage  of  data  points 
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in  this  zone: 

regional  spread  of  points 
within  this  zone: 
north: 
south: 


east: 


west: 


0.799489 


5092049.155918 

5049238.983803 

734139.517650 

732514.747908 


INFO  FOR  ZONE  2: 
zone  number: 
percentage  of  data  points 
in  this  zone: 

regional  spread  of  points 
within  this  zone: 
north: 
south: 

east: 

west: 


14 


99.200508 


5092041.463966 

5036134342322 

398030.217441 

265527.656108 


If  the  user  does  not  input  the  UIM  zone  number,  it  is  calculated  for  them.  Then  the  zone  number  and 
region  information  are  output,  and  if  the  program  finds  that  the  input  data  contains  information  in  more 
than  one  UIM  zone,  then  the  output  is  given  for  all  applicable  zones. 


If  instead  the  user  supplies  the  UIM  zone  number,  the  output  would  look  like  that  shown  below: 

REGION  FOR  THIS  DATA  FILE: 

north  border: 
south  border: 
east  border: 
west  border: 

(zone  number: 

NOTES 

This  command  must  be  compiled  separately.  It  resides  in  the  sic.alpha  directory  and  will  not 
automatically  be  included  in  the  compile  of  the  main  GRASS  code.  Although  nutiger. region  does  not 
need  a  FORTRAN  compiler,  it  is  used  to  support  other  TIGER  data  functions  (like  v.db.rim,  v.in.tiger, 
and  rim)  that  do  require  access  to  a  FORTRAN  compiler. 

TIGER  data  are  presented  in  latitude/longitude  format,  and  are  converted  to  UIM  coordinates  using 
coordinate  conversion  routines  contained  in  the  GRASS  library.  If  no  UIM  zone  number  is  supplied  by 
the  user,  the  program  calculates  the  appropriate  zone(s)  based  on  the  input  data  provided.  The  outptut 
then  provides  the  UTM  zone  numbers  found  (if  more  than  one),  the  geographic  region  covered  within 
each  zone,  and  the  percentage  of  data  points  found  in  each  zone.  The  user  must  then  decide  which  of 
these  UTM  zones  contains  the  major  or  most  important  portion  of  data  values,  so  that  the  zone  number 
can  be  supplied  in  creating  the  GRASS  location  to  hold  the  imported  data  and  can  be  provided  to  the 
importing  program  ( v.in.tiger ).  Zone  edges  will  be.  extended  (reasonably)  to  include  data  values  lying 
outside  the  chosen  zone.  If  desired,  nuiger. region  can  be  re-run,  supplying  the  chosen  zone  numlxr, 
in  order  to  evaluate  the  region  edges  of  the  itput  data  set  (with  the  extended  zone). 

FILES 

Source  code  for  RIM  is  fixated  under  $GISBASF/../src.rdatal/rim 

Source  code  for  v.db.rim  is  located  under  $GISBASF/./src.garden/grass.rimA  .db.rim 


5092049.155918 

5036134342322 

398030217441 

265527.656108 

14) 


(  rRASS  -!  .0  (Summer  I'1' ' !  i 


l  \S.  Anm  <  I  K  I 


I'M 


m.tiger  .region 


GRASS  Reference  Manual 


m  Jig  er. region 


Source  code  for  v. in. tiger  is  located  under  SGISBASE/.  ./src.garden^grass.tigerA'  in.tiger 
Source  code  for  mMgersegion  is  located  under  SGISBASE/.  .7srcgarden/^rass  Jig  er/mJiger .region 
SEE  ALSO 

GenMaps,  GenJractmap,  gjegion,  v.db.rim,  v.inJiger,  tiger infojh 

AUTHOR 

Marjorie  Larson,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

m  u2ll  -  Converts  Universal  Transverse  Mercator  (UrM)  coordinates  to  geographic  (latitude/longitude) 
coordinates. 

(GRASS  Data  Import/Processing  Program) 

SYNOPSIS 

mJi2Il 
m.u2II  help 

m.u211  [-arwo]  spheroid  =name  [z ane=value]  [input  =name]  [ output  =name\ 

DESCRIPTION 

m.u21l  converts  Universal  Transverse  Mercator  (UTM)  northii^s  and  eastings  to  geographic  coordinates 
(i.e.,  latitudes  and  longitudes).  The  user  must  specify  the  UTM  coordinates  to  be  converted  and  the 
spheroid  on  which  the  geographic  coordinates  will  be  based.  The  program  also  needs  to  know  the 
UTM  zone  in  which  the  input  coordinates  are  located.  However,  if  the  user  is  running  GRASS  from  a 
UTM  data  base  LOCATION,  m.u2Il  will  use  this  data  base’s  UTM  zone  designation,  if  no  zone  is 
specified  by  the  user. 

The  GRASS  program  m.ll2u  performs  the  reverse  operation,  converting  geographic  coordinates  to  UTM 
coordinates. 

The  list  of  spheroids  available  is  somewhat  dynamic.  At  the  time  of  this  release,  available  spheroids 
included:  airy,  australian,  bessel,  clark66,  everest,  grs80,  hayford,  international,  krasovsky,  wgs66, 
wgs72,  and  wgs84  (see  table  below'). 

This  command  can  be  run  either  non-interactively  or  interactively.  The  user  can  run  the  program  non- 
interactively  by  entering  desired  flag  settings  and  parameter  values  on  the  command  line  using  the 
following  format: 

nui211  [-srwo]  spheroid  name  [ zone  =va/ue]  [input  name]  [ output  -  name \ 

Alternately,  the  user  can  simply  type: 

moi2II 

on  the  command  line.  In  this  case,  the  user  will  be  prompted  for  parameter  values  and  fl;ig  settings 
through  the  standard  interface  described  in  the  manual  entry  for  parser. 

Input  can  be  entered  from  the  keyboard  or  from  an  input  file.  In  either  case,  input  should  lie  entered 
with  one  UTM  easting  and  northing  pair  per  line,  in  the  format  shown  below: 

casting  northing 
easting  northing 
easting  northing 
easting  northing 


end 

If  the  user  sets  the  -r  flag,  nuu2ll  will  expect  die  order  of  the  coordinates  to  be  reversal,  aixl  stated  as 
northing,  easting  pairs,  rather  than  as  easting,  northing  pairs.  This  is  useful  for  passir^  ASCII  GRASS 
vector  (/dig)  files,  whose  coordinates  are  stated  as  nortliing,  easting  pairs,  directly  through  m.u2ll. 

Similarly,  the  user  can  elect  to  send  output  to  an  output  file  or  (by  default)  to  standard  output  (the 
user’s  terminal  screen).  Ix  ample  input  and  output  are  shown  below  (see  EXAMPIJE). 

Program  flag  settings  and  jiarameters  have  the  following  meanings. 
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Flag* 


-s 

-r 


-w 

-o 

Prrauirtmr 


Specified  UTM  zone  is  in  the  southern  hemisphere. 

The  order  of  coordinates  is  reversed  in  the  input,  and  entered  as:  north  east. 
This  option  allows  the  user  to  pass  an  ascii  vector  file  through  nut2U. 

Do  not  flag  invalid  east,  north  input  lines  as  errors. 

Bag  other  invalid  input  lines  as  errors. 


spheroid  =name 


zon  revalue 

input  =name 
output  =name 


Reference  spheroid  (ellipsoid). 

Options:  airy,  australian,  bessd,  clark66,  everest,  grs80,  hayford,  international, 
krasovsky,  wgs66,  wgs72,  wgs84 

UTM  zone  in  which  UTM  coordinates  are  located. 

Options:  1-60 

Name  of  input  file  containing  UTM  values  to  be  converted. 

Name  to  be  assigned  to  output  file  containing  longitude  and  latitude  values. 


AVAILABLE  SPHEROOS 

(The  on-line  listing  includes  only  the  spheroid  names.) 


Spheroid: 

Semi-major  axis 
(Equatorial  Radius)  (a): 

Eccentricity  sqrd  (e),  Flattening  (f), 
or  Polar  Radius  (b): 

Commonly  used  for 

airy 

a=6377563396 

e=.006670540 

australian 

a=6378160 

f=l/29825 

Australia 

bessd 

a=6377397.155 

e=.006674372 

Japan 

clark66 

a=6378206.4 

b=6356583-8 

N.  America 

everest 

a=6377276345 

e =.0066378466 

India,  Burma 

grs80 

a=6378137 

f=l/298257 

hayford 

a=6378388 

f=l/297 

international 

a=6378388 

1=1091 

Europe 

krasovsky 

a=6378245 

f =1/298 3 

wgs66 

a=6378145 

f=l/29825 

worldwide  coverage 

wgs72 

a=6378135 

f=l/29826 

worldwide  coverage 

wgs84 

a=6378137 

f=l/298257223563 

worldwide  coverage 

EXAMPLE 

Assume  the  user  has  input  the  command: 


mju2)l  -s  spheroid  =wgs72  zone  =4  input  =utuji^lc  output  =U.outflte 

where  the  input  file  utminfUe  contains  the  following  easting  and  northing  UTM  coordinate  valivs  and 
zone  designations: 


23774035  2167292.10 
238740 IX)  2167000.00 
239000.00  2167100.00 
237100.00  2166000.00 
end 


Output  would  then  be  sent  to  the  output  file  lljoutfe,  containing  the  below  longitude  and  latitude 
coordinate  values: 

16602:25 .645137W  70:27 :46.615528S 
16600:53 237056W  7027:59. 692673S 
16600:27 23258W  7027:57.454281S 
16603:4 1.428895W  702825.61617S 
end 
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NOTES 

Users  can  add  information  to  the  ellipsoid  parameter  definition  file  on  their  systems  (located  in 
$GISBASE/etc/ellipse.table)  to  add  spheroids  not  now  among  those  supported  by  GRASS. 

See  mJl2u  for  a  brief  discussion  of  spheroids. 

The  UTM  zone  designation  determines  on  what  area  of  the  earth  a  point  is  found.  The  same  UTM 
coordinates  will  be  found  in  each  different  UTM  zone.  Look  at  the  marginalia  of  your  source  map  to 
determine  into  which  UTM  zone  your  UTM  coordinates  fall.  Although  the  user  can  permissibly  omit 
specification  of  a  UTM  zone  when  running  this  program  under  a  UTM  data  base  LOCATION,  it  is 
safer  to  specify  it  (see  DESCRIPTION,  above). 

nuu2ll  converts  the  first  pair  erf  coordinates  on  each  line  of  input  and  leaves  anything  else  on  the  line 
alone.  If  a  line  begins: 

XXXXXX.XX  XXXXXXXJCX 

then  the  xxxxxxxx  xxxxxxxjcx  UTM  coordinate  pair  is  converted  to  a  longitude,  latitude  pair.  Any 
other  information  appearing  on  the  line  is  left  alone.  If  the  line  doesn’t  begin  with  a  pair  of  coordinates 
in  the  above  format,  then  the  line  is  left  as  it  is. 

FILES 

See  ellipsoid  parameter  definition  file  in  $GISBASE/etc/ellipse.tab!e. 

SEE  ALSO 

For  australian,  clark66,  grs80,  hayford,  international,  krasovsky,  and  wgs72  ellipsoid  parameters,  see: 
John  P.  Snyder,  Map  Projections  -  A  Working  Manual ,  U.S.  Government  Printing  Office, 
Washington  DC,  1989.  U.S.  Geological  Survey  Professional  Paper  1395;  from  Table  1,  p.12. 

For  bessel,  airy,  everest,  and  wgs66  ellipsoid  parameter  values,  see: 

Thomas  O.  Seppelin,  The  Department  of  Defense  World  Geodetic  System  1972,  presented  at  the 
International  Symposium  on  Problems  Related  to  the  Redefinition  of  North  American  Geodetic 
Networks,  Fredericton,  New  Bninswick,  Canada  in  May,  1974;  see  Table  9,  p35. 

For  wgs84  parameter  values,  see: 

U.S.  Naval  Oceanographic  lairs. 

Also  read  GRASS  Users  Reference  Manual  entries  for 

(Llabels,  d.points,  dsites,  d.where,  m.datumshift,  m.gc2ll,  m.U2gc,  m.ll2u,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p.chart  -  Prints  the  color  chart  of  the  currently  selected  printer. 

(GRASS  Hardcopy  Output  Program) 

SYNOPSIS 

pxhart 

DESCRIPTION 

This  function  prints  the  color  chart  of  the  user’s  hardcopy  color  printer.  The  colors  in  the  chart  are 
numbered  with  the  (device-dependent)  number  associated  with  each  color.  This  function  is  useful  both 
for  the  p. colors  command  as  well  as  for  color  selection  with  pjrtap. 

The  user  must  select  a  printer  using  p. select  before  running  this  command. 

SEE  ALSO 

dxolors,  p.colors,  p.map,  p.select,  r. colors 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p.colors  -  Allows  the  user  to  develop  a  color  table  that  associates  map  categories  with  user- specified 
printer  colors. 

(GRASS  Hardcopy  Output  Program) 

SYNOPSIS 

p.coiors 

DESCRIPTION 

This  function  allows  the  user  to  modify  a  color  table  for  a  raster  map  layer,  by  assigning  colors  to  the 
categories  in  the  raster  map  layer  based  on  printer  color  numbers  (instead  of  red,  green,  blue 
percentages). 

The  user  will  need  to  have  the  printer  color  chart  available  to  properly  select  the  colors  (see  manual 
entry  for  p. chart). 

The  p.colors  function  allows  the  user  to  exercise  perfect  control  over  the  colors  that  appear  in  the 
hardcopy  image. 

NOTES 

If  the  user  assigns  a  printer  color  number  outside  of  the  printer’s  range,  p. colors  will  not  complain,  but 
will  not  save  the  out-of  range  printer  color  number  to  the  raster  map  layer’s  color  table. 

This  command  modifies  the  color  table  associated  with  a  map  layer,  and  will  therefore  also  affect  the 
colors  in  which  a  map  layer  is  displayed  on  the  user’s  graphics  monitor.  (See  map  color  table  files 
stored  under  SLOCAIION/colr  and  $LOCVmON/colr2.) 

SEE  ALSO 

cLcolors,  pjehart,  pmap,  r. colors 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p. icons  -  Oeates  and  modifies  icons  for  map  display  and  output. 

(GRASS  Hardcopy  Output  Program) 

SYNOPSIS 

paeons 

DESCRIPTION 

This  program  allows  the  user  to  create  and  maintain  icons  which  are  used  by  the  pjnap  and  d Jeans 
commands  to  depict  sites. 

FILES 

Icon  files  created  by  the  user  are  stored  under  SLOCATION/icans. 

SEE  ALSO 

d.icons,  d. points,  djites,  pjnap,  s.menu 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p.labels  -  Create  labels  for  hardcopy  maps. 

(GRASS  Hardcopy  Out  pul  Program) 

SYNOPSIS 

pJabds 

DESCRIPTION 

This  module  allows  the  user  to  create  or  modify  labels  files.  These  labels  files,  which  are  stored  in  the 
database,  define  text  information  fix  printing  with  p.map  and  for  graphics  display  with  d.paint. labels. 
Each  label  'tas  components  which  determine  the  text,  the  location  of  the  text  on  the  image,  its  size,  and 
the  background  for  the  text. 

The  interface  is  a  screen-oriented  input/edit  layout.  Each  label  is  entered  with  a  single  screen.  After 
filling  in  the  required  information  (described  below),  the  user  hits  <£SC>to  accept  the  label  and  :;tart  a 
new  one.  After  the  first  label  has  been  accepted,  the  user  then  hists  the  <ESC>  one  more  time  (on  an 
empty  label  screen)  to  exit  the  module  and  save  the  labels. 


SCREEN  LAYOUT 

The  screen  layout  for  the  labels  looks  like  this: 


PAINI'  LABELS:  labelfile  new  labels  [1] 

TEXT: _ SKIP:  no_ 


LOCATION:  EAST: _  OFFSET: _ 

NORTH _  OFFSET: _ 

PLACEMENT:  center _ 

FONT:  standard _ 

TEXT  SIZE:  500 _ 

TEXT  COLOR:  black _  WIDTH  1 _ 

LUGHLIGHI  COLOR:  none _  WIDllLO. 

BACKGROUND  COLOR:  white _ 

BORDER  COLOR:  black _ 

OPAQUE  TO  VECTORS:  yes _ 


AFTER  COMPUTING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


The  lalxl  information  that  must  be  provided  is: 

TEXT:  Up  to  four  lines  of  text.  Lines  in  multiple  line  labels  will  appear  one  above  the  next. 

SKIP:  yes|no.  If  no,  label  will  be  printed.  If  yes,  the  label  will  lx  retained  in  the  file  1  Hit  not  printed. 
LOCATION:  Detennines  where  the  text  will  be  fixated  on  the  image.  The  user  specifies  the  easting 
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and  northing,  and  (optionally)  specifies  a  vertical  and  horizontal  offset  (in  printer  pixels)  from  the 
specified  easting/northing.  (Hie  vertical  offset  will  shift  the  location  to  the  south  if  positive,  north  if 
negative.  The  horizontal  offset  will  shift  the  location  east  if  positive,  west  if  negative.)  These  offsets  are 
provided  to  allow  finer  placement  of  labels. 

PLACEMENT:  Determines  which  part  of  the  label  to  which  the  location  refers.  If  placement  is 
unspecified,  the  label  is  centered  (center),  by  default.  Label  placement  may  be  specified  as: 


lower  left 
lower  right 
low  er  center 


(lower  left  comer  of  the  text) 
(lower  right  comer  of  the  text) 
(bottom  center  of  the  text) 


upper  left 
upper  right 
upper  center 


(upper  left  comer  of  the  text) 
(upper  right  comer  of  the  text) 
(top  center  of  the  text) 


center 


(center  of  the  text) 


FONT:  This  specifies  the  font  to  use.  The  following  fonts  are  available: 

cyrilc  godigbt  gothgrt  gothitt  greekc  greekcs  greekp  greeks  italicc  italiccs  italict  romanc 
iumancs  romand  romans  romant  scriptc  scripts 

The  word  standard  can  be  used  to  sped  (y  the  default  font  (which  is  romans). 

TEXT  SIZE:  This  determines  the  size  of  the  letters.  The  d->e  specifies  the  vertical  height  of  the  letters 
in  meters  on  the  ground.  Thus  text  will  grow  or  shrink  departing  on  the  scale  at  which  the  map  is 
drawn.  The  default  text  size,  if  none  is  specified,  is  500. 

TEXT  COLOR:  This  selects  the  text  color.  If  unspecified,  the  label’s  text  is  drawn  in  black,  by 
default.  The  text  color  can  be  specified  in  one  of  four  ways: 

1)  By  color  name: 

aqua  black  blue  brown  cyan  gray  green  grey  indigo  magenta  orange  purple  red  violet 
white  yellow 

2)  As  red,  green,  Hue  percentages,  for  example:  5  A  .7 

(This  form  is  not  supported  by  d.paint. labels.) 

3)  By  printer  color  number  to  get  the  exact  printer  color. 

(This  form  is  not  supported  by  d.paint. labels) 

4)  Specify  none  to  suppress  the  lettering. 

WIDTH:  This  determines  the  line  thickness  of  the  letters.  The  normal  text  width  should  be  set  to  1. 
larger  numbers  can  be  used  to  simulate  bold  face.  ( d.paint Jabels  ignores  this  value  and  always  uses  1. 
1  is  also  the  default  width  to  w  hich  the  width  is  set  by  paint,  if  none  is  specified  by  the  user.) 

HIGHLIGHT  COLOR:  The  text  c:ut  lie  highlighted  in  another  color  so  that  it  appears  to  be  in  two 
colors.  The  text  is  drawn  first  in  this  color  at  a  wider  line  width,  and  then  redrawn  in  the  text  color  at 
the  regular  line  width.  No  highlight  color  (none)  is  used,  by  default,  if  unspecified  by  the  user.  To 
specify  use  of  no  highlight  color,  specify  none.  (See  TEXT  COJGR  above  for  a  list  of  permissible 
color  names.) 
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HIGHLIGHT  WIDTH:  Specifics  how  far  from  the  text  lines  (in  units  of  pixels)  the  highlight  color 
should  extend.  Ihe  default  highlight  width  is  set  to  0  (i.e..  no  highlight  color). 

BACKGROUND  COLOR:  Text  may  lx:  Ixixed  in  a  solid  color  by  specifying  a  background  color. 
Specify  none  for  no  background.  The  default  background  color  setting,  if  unspecified  by  the  user,  is 
white.  (See  TEXT  COLOR  above  for  a  list  of  permissible  color  names). 

BORDER  COLOR:  Select  a  color  for  the  Ixxder  around  the  background.  Specify  none  to  suppress 
the  border.  The  default  border  color  used,  if  unspecified,  is  black.  (See  TEXT  COLOR  above  fix  a 
list  of  permissible  color  names.) 

OPAQUE  TO  VECTORS:  yes\no.  This  field  only  has  meaning  if  a  background  color  is  selected. 
yes  will  prevent  vector  lines  from  entering  the  background,  no  will  allow  vector  lines  to  enter  the 
background.  The  default  setting,  if  unspecified  by  the  user,  is  yes. 

SEE  ALSO 

p.rmp,  pselect,  p.icons,  d.paint. labels 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p.map  -  Hardcopy  color  map  output  utility. 

(GRASS  Hardcopy  Output  Program) 

SYNOPSIS 

p.map 
pjnap  help 

panap  [input  =name]  [ scale  =mapscale) 

DESCRIPTION 

p.map  produces  hardcopy  color  map  products  on  your  system’s  color  output  device.  Output  can 
include  a  raster  map,  any  number  of  vector  overlays,  site  data,  text  labels,  and  other  spatial  data. 

Ibis  program  has  2  distincts  modes  of  operation.  The  command-line  mode  requires  the  user  to  prepare 
a  file  of  mapping  instructions  describing  the  various  spatial  and  textual  information  to  be  printed  prior 
to  running  pjnap.  The  interactive  mode  (i.e.,  no  command- line  arguments)  wifi  prompt  the  user  for 
items  to  be  mapped  and  does  not  require  the  user  to  prepare  a  file  of  instructions. 

The  command- line  parameters  are: 

input  name  Hie  containing  mapping  instructions,  (or  enter  input=-  to  enter  from  keyboard). 

These  instructions  are  described  in  detail  below. 

scale  =mapscale  Scale  of  the  output  map,  e.g.,  1:25000 
Default:  1  panel 

This  parameter  is  provided  as  a  convenience.  It  is  identical  to  the  scale  mapping 
instruction  described  below. 


Note:  the  user  must  select  an  output  device  using  pjelect  before  running  pjnap.  Also,  the  preview 
device  can  be  selected  to  view  die  output  from  pjnap  on  the  graphics  monitor  instead  of  serving  it  to  a 
paper  printer. 

MAPPING  INSTRUCTIONS 

The  mapping  instructions  allow  the  user  to  specify  various  spatial  data  to  be  plotted.  These  instructions 
are  normally  prepared  in  a  regular  text  file  using  a  system  editor.  Some  instructions  are  angle  line 
instructions  while  others  are  multiple  line.  Multiple  line  instructions  consist  of  the  main  instruction 
followed  by  a  subsection  of  one  or  more  additional  instructions. 


colormode 

Selects  the  appropriate  method  to  color  raster  map  layers  and  images. 

USAGE:  colormode  approx  |  best 

Ihere  are  two  methods:  approximate  and  best.  From  a  user  perspective,  approximate  can  be  used  for 
raster  map  layers  with  few  categories,  such  as  soils,  and  best  should  be  used  for  images  like 
LANDS  AT  images  or  NHAP  photos,  or  maps  with  many  categories.  The  approximate  mode  treats 
each  pixel  independently,  giving  it  the  printer  color  that  best  approximates  the  hue  color.  The  best 
mcxle  "blends"  colors  from  pixel  to  pixel  using  a  dithering  techiique  to  simulate  more  colors  than  the 
printer  can  actually  print.  The  default,  if  unspecified,  is  best. 

Ihis  example  would  select  the  approximate  colormode.  The  assumption  is  that  the  raster  map  layer 
being  printed  has  few  colors  or  that  the  colors  would  not  look  good  dithered. 

EXAMPI T.:  colonnou.'  approx 
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color  table 

Includes  the  color  table  for  the  raster  map  layer  in  the  legend  below  the  map 
USAGE:  color  table  [y  |  n] 

The  color  table  will  display  the  colors  for  each  raster  map  layer  category  value  and  the  category  label. 
To  get  a  color  table,  you  must  have  previously  requested  a  raster  map  layer.  Omitting  the  colortable 
instruction  would  result  in  no  color  table.  Note:  Be  careful  about  asking  for  the  color  table  for  a 
raster  map  layer  that  contains  many  categories,  like  an  elevation  layer;  this  could  result  in  the  printing 
of  an  extremely  long  color  table. 

This  example  would  print  a  color  table  as  part  of  the  legend  to  the  map. 

EXAMPLE:  colortable  y 


coma  eats 

Prints  comments  beneath  the  map.  You  may  submit  comment  text  line  by  line  during  pjnap  execution 
or  a  via  a  prepared  comments  file. 

USAGE  comments  [commentfile] 
comments 

end 

This  example  prints  the  comment  "This  is  a  comment"  in  the  legend  below  the  map. 

EXAMPLE  comments 

This  is  a  comment. ' 

end 

This  example  prints  whatever  is  in  the  file  veg. comments  in  the  legend  below  the  map. 

EXAMPLE  raster  vegetation 

comments  veg  .comments 

end 

Presumably,  the  file  veg.comments  contain  comments  pertaining  to  the  raster  map  layer  vegetation, 
such  as  "This  map  was  created  by  classifying  a  LANDSAT  TM  image." 


defpst 

Defines  area  fill  patterns  to  be  used  in  the  setpat  instruction. 

USAGE  defpst  name 
pattern 
color  #  color 

end 


The  pattern  is  given  a  name  on  the  defpat  instruction  line.  The  pattern  which  follows  is  composed  of  a 
sequence  of  numbers  0-9  (and  blanks,  which  are  equivalent  to  0).  The  Hanks  or  zeros  indicate  holes  in 
the  pattern  where  the  normal  category  color  would  show  thru.  The  other  numbers  1-9  indicate  pattern 
pixels  and  can  be  assigned  any  color.  The  default  color  for  all  the  digits  will  be  Hack  unless  specified 
with  the  color  iastruction.  The  color  option  will  Ivgin  by  entering  the  word  color  followed  by  one  of 
the  digits  (1-9)  in  the  pattern,  followed  by  one  of  the  NAMED  COLORS .  This  should  be  repeated  for 
oath  of  the  digits  specified  to  avoid  using  black.  The  instruction  end  terminates  the  pattern  definition. 
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Of  course,  the  user  can  define  more  patterns  by  altering  more  defpat  instructions. 

NOTE:  Do  NOT  indent  the  pattern.  Leading  Hank  spaces  will  be  interpreted  as  0’s. 

This  example  creates  a  black  horizontal  line  pattern. 

EXAMPLE:  defpat  hcriz 
1 
0 
0 
0 

color  1  black 
cad 

This  example  creates  a  green  vertical  line  pattern. 

EXAMPLE  defpat  vert 
1000 

color  1  green 
cad 

This  example  creates  a  red  diagonal  line  pattern. 

EXAMPLE  defpat  diag 
00001 
0001 
001 
01 
1 

color  1  red 
cad 

This  example  creates  a  two-toned  tree  pattern  with  orange  trunks  and  green  leaves. 
EXAMPLE  defpat  tree 

2 

222 
22122 
22  122 
1 

2 

222 
22122 
22  122 
1 

color  1  orange 
color  2  black 
cad 


grid 

Overlays  a  coordinate  grid  onto  the  output  map. 

USAGE  grid  spacing 
color  color 
numbers  #  [color] 
aid 
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Ihe  spacing  of  the  grid  is  given  (in  the  geographic  coordinate  system  units)  on  the  main  instruction 
line.  The  subsection  instructions  allow  the  user  to  specify  the  color  of  the  grid  lines,  whether 
coordinate  numbers  should  appear  on  the  grid  lines,  and  if  they  should  appear  on  every  grid  line  (1), 
every  other  grid  line  (2),  etc.,  and  what  color  the  numbers  should  be.  Ihe  defaults  are  black  grid  lines, 
unnumbered. 

This  example  would  overlay  a  green  grid  with  a  spacing  of  10000  meters  (for  a  metered  database,  like 
UTM)  onto  the  output  map.  Alternate  grid  lines  would  be  numbered  with  red  numbers. 

EXAMPIE:  grid  10000 
color  green 
numbers  2  red 
end 


labels 

Selects  a  labels  file  for  output  (see  manual  entry  for  p.labels). 

USAGE:  labels  labelfile|  lia 

This  example  would  paint  labels  from  the  labels  file  called  tawn.namts.  Presumably,  these  labels 
would  indicate  the  names  of  tow  ns  on  the  map. 

EXAMPLE:  labels  townnames 


line 

Draws  lines  on  the  output  map. 

USAGE:  line  east  north  east  north 

line  x%  y%  x%  y% 

color  color 
width  # 
masked  [y|n] 
end 

The  beginning  and  ending  points  of  the  line  are  entered  on  the  main  instruction.  These  points  can  be 
defined  either  by  map  coordinates  or  by  using  percentages  of  the  geographic  region.  The  user  may  also 
specify  line  color,  width  in  pixels,  and  if  the  line  is  to  be  masked  by  the  current  mask.  (See  manual 
entry  for  r.rnask  for  more  information  on  the  mask.) 

This  example  would  draw  a  yellow  line  from  the  point  x  =10%  y  =80%  to  the  point  x  =30%  y  =70%. 
This  line  would  be  2  pixels  wide  and  would  appear  even  if  there  is  a  mask. 

EXAMPIJl:  line  10%  80%  30%  70% 
color  yellow 
width  2 
masked  n 
end 

Of  course,  multiple  lines  may  be  drawn  with  multiple  line  instructions. 
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outline 

Outlines  the  areas  erf  a  raster  map  layer  with  a  specified  color. 

USAGE:  oatline 

color  color 
end 

Distinct  areas  erf  the  raster  map  will  be  separated  from  each  other  visually  by  drawing  a  border  (or 
outline)  in  the  specified  color  (default:  black).  Note:  it  is  important  die  user  enter  the  instruction  end 
even  if  a  color  is  not  chosen.  (It  is  hoped  that  in  the  future  the  outline  erf  a  different  raster  map  layer 
other  than  the  one  currently  being  painted  may  be  placed  on  the  map.) 

This  example  would  outline  the  category  areas  of  the  soils  raster  map  layer  in  grey. 

EXAMPLE:  raster  soils 

outline 
color  grey 
cod 


point 

Places  additional  points  or  icons  on  the  output  map. 

USAGE:  point  east  north 

point  x%  y% 
color  color 
icon  iconfile|  list 

size  # 

masked  [y|n] 
end 

The  point  location  is  entered  in  the  main  instruction  line  by  giving  either  the  map  coordinates  or  by 
using  percentages  erf  the  geographic  region.  The  user  may  also  specify  the  point  color,  die  icon  file  to 
be  used  to  represent  the  paint  location  (see  the  die  manual  entry  for  pJcons),  die  rise  erf  die  icon  in 
integer  multiples  erf  the  pattern  in  the  icon  file,  and  whether  die  point  is  to  be  madked  by  die  current 
mask.  (See  manual  entry  for  rjnosk.  for  more  information  on  die  mask.) 

This  example  would  place  a  purple  diamond  (from  icon  file  diamond)  at  the  point  (E456000 
N7 890000).  This  diamond  would  be  die  same  size  it  is  in  the  diamond  icon  file  and  would  not  be 
masked  by  the  current  mask. 

EXAMPLE:  point  456000  7890000 

color  purple 
icon  diamond 
die  1 


Of  course,  multiple  points  may  be  drawn  with  multiple  paint  instructions. 


raster 

Selects  a  raster  map  layer  for  output. 
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USAGE:  raster  mapname|  list 

For  each  pjnap  run,  only  one  raster  map  layer  can  be  requested.  If  no  raster  map  layer  is  requested,  a 
completely  white  map  will  be  produced.  It  can  be  useful  to  select  no  raster  map  layer  to  provide  a 
white  background  for  vector  images. 

Ibis  example  would  paint  a  map  of  the  taster  map  layer  soils. 

EXAMPLE  raster  soils 


read 

Provides  p.map  with  a  previously  prepared  input  stream. 

USAGE  read  previously  prepared  UNIX  file 

Mapping  instructions  can  be  placed  into  a  file  and  read  into  pjnap. 

Note:  pjnap  will  not  search  for  this  file.  The  user  must  be  in  fire  coned  directory  or  specify  the  full 
path  on  the  read  instruction.  (Note  to  Arin/csh  users:  ~  won’t  work  with  this  instruction). 

This  example  reads  fire  UNIX  file  pmapjoads  into  pjnap.  This  file  may  contain  all  the  p.map 
instructions  for  placing  file  vector  map  layer  roads  onto  the  output  map. 

EXAMPLE  read  pmap.roads 

The  user  may  have  created  this  file  because  this  vector  map  layer  is  particularly  useful  for  many  p.map 
outputs.  By  using  the  read  option,  the  user  need  not  enter  all  the  input  for  the  vector  instruction,  but 
simply  read  the  previously  prepared  file  with  the  correct  instructions. 


region 

Places  the  outline  of  a  smaller  geographic  region  on  the  output. 

USAGE  region  regionfile|  list 
color  color 
width# 
end 


Geographic  region  settings  are  created  and  saved  using  gjegion.  The  pjnap  region  option  can  be 
used  to  show  an  outline  of  a  smaller  region  which  was  printed  on  a  separate  run  of  p.map  on  other 
user-created  maps. 


The  user  can  specify  the  color  and  the  width  (in  pixel  units)  of  the  outline.  The  default  is  a  black 
border  of  one  pixel  width. 

This  example  would  place  a  white  outline,  2  pixels  wide,  of  the  geographic  region  called  fire. zones 
onto  the  output  map.  This  geographic  region  would  have  been  created  and  saved  using  g. region. 

EXAMPLE  region  fire  .zones 
color  white 
width  2 
end 
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•calc 

Selects  a  scale  for  the  output  map. 

USAGE:  scale  scale 

The  scale  can  be  selected  either  as: 

a  relative  ratio,  eg.,  1:25000; 
an  absolute  width  of  the  printed  map,  eg.,  10  inches; 
the  number  of  printed  paper  panels,  eg.,  3  panels; 
the  number  of  miles  per  inch,  eg.,  1  inch  equals  4  miles. 

This  example  would  set  the  scale  of  the  map  to  1  unit  =  25000  units. 
EXAMPLE:  scale  1:25000 


•etcoler 

Oerrides  the  color  assigned  to  one  or  more  categories  of  the  raster  map  layer. 
USAGE:  set  color  cat(s)  color 


This  example  would  set  the  col  or  for  categories  2,  5,  and  8  of  the  raster  map  layer  watersheds  to  white 
and  category  10  to  green.  (NOTE:  no  spaces  are  inserted  between  the  category  values.) 

EXAMPLE:  raster  watersheds 

aetcolor  2,5,8  white 
set  col  or  10  green 

Of  course,  setccior  can  be  requested  more  than  once  to  ewenide  the  default  color  for  additional 
categories.  More  than  one  category  can  be  changed  far  each  request  by  listing  all  the  category  values 
separated  by  commas  (but  with  no  spaces). 


Mtflt 

Assigns  a  (previously  defined)  pattern  on  a  raster  map  layer  category. 

USAGE:  aetpat  cat  name 

or  aetpat  builtin 

or  aetpat  all 

The  user  can  choose  to  use:  the  name  of  a  specific  pattern  created  using  rkfpa*  (see  above);  the 
patterns  built  into  pjnap-,  or  all  the  patterns  the  user  may  have  created. 

This  example  assigns  the  vertical  pattern  created  using  dcfjpai  (see  example  in  defpat  above) 
category  3  of  the  raster  map  layer  vegetation  and  the  tree  pattern  (see  example  in  deffrat  above) 
category  10. 

EXAMPLE:  raster  veg 
aetpat  3  vert 
aetpat  10  tree 


This  example  reads  a  previously  prepared  UNIX  file  horiz.pat  with  the  correct  defpat  instructions  for 
creating  a  black  horizontal  pattern  (see  example  in  defpat  above)  and  assigns  that  pattern  to  category  5 
of  the  raster  map  layer  soils  via  the  aetpat  instruction. 
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EXAMPLE:  raster  soils 
read  boriz.pat 
act  pat  5  hcriz 

To  select  the  buildn  patterns: 

EXAMPLE  raster  soils 
set  pat  buildn 

To  select  individual  buildn  patterns: 

EXAMPLE  raster  soils 
setpat  5  4A 
set  pat  10  & 

sites 

Selects  sites  data  to  be  placed  on  the  output  map  (see  manual  entry  for  s.menu). 

USAGE  sites  sitemap!  list 
color  color 
icon  iconfile|  list 
size  # 
deac  [y|  n] 
end 

The  user  may  specify  the  color  of  the  sites  (see  section  on  NAMED  COLORS  below);  the  icon  to  be 
used  to  represent  the  presence  of  a  site  (see  the  manual  entry  for  p.icons );  the  rize  of  the  icon  (number 
erf  times  larger  than  the  size  it  is  in  the  icon  file);  and  whether  or  not  the  description  associated  with 
each  site  is  also  to  be  printed. 

This  example  would  paint  a  sites  map  with  Hue  w  indmills  (from  an  icon  file  created  by  the  user  using 
the  pjeons  GRASS  command)  placed  at  all  windmill  locations  (from  a  sites  list).  These  windmills 
would  be  two  times  larger  than  the  size  of  the  icon  in  the  icon  file  and  have  descriptions  from  the  sites 
list  file  printed  beside  them. 

EXAMPLE  rite*  windmills 
color  Hue 
icon  windmill 
ze  2 
deac  y 
cad 

text 

Places  text  on  the  map. 

USAGE  text  east  north  text 
text  x%  y%  text 
font  fontname 
color  cdor|  none 

width  # 

heal  or  calor|  none 

hwidth  # 

background  colcr|  none 
border  color  |  none 

rfze  # 

ref  reference  point 

x  off  set  # 
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y  offset  # 

opMpe[y|n] 

end 


Ihe  user  specifies  where  the  text  will  be  placed  by  providing  map  coordinates  or  percentages  erf  the 
geographic  region  map.  The  text  follows  these  coordinates  on  the  same  instruction  line.  More  than  one 
line  of  text  can  be  specified  by  notating  the  end  of  a  line  with  'n  (eg.  USANnCERL). 


The  user  can  then  specify  v  arious  text  features: 

font:  cyrilc  gothgbt  gothgrt  gothitt  groeke  greekes  greekp  greeks  italiee  itaiiccs  italict  romanc  romancs 
romand  romans  romani  scriptc  scripts  (The  default  font  is  romans); 

color  (see  NAMED  COLORS); 

width  of  the  lines  used  to  draw  the  text  (to  make  thicker  letters); 

size  as  the  vertical  height  of  the  letters  in  meters  on  the  ground  (text  size  will  grow  or  shrink 
depending  on  the  scale  at  which  the  man  is  painted); 

the  highlight  color  (hcolor)  and  the  width  of  the  highlight  color  (hwidth); 

the  text  endosing  box  background  color;  the  text  box  border  color; 

ref.  This  reference  point  specifies  the  text  handle  -  what  part  of  the  text  should  be  placed  on  the 
location  specified  by  the  map  coordinates.  Reference  points  can  refer  to: 
[lower |  upper |  center]  [ left |  right |  center]  of  the  text  to  be  printed; 

y offset,  which  provides  finer  placement  of  text  by  shifting  the  text  a  vertical  distance  in  pixels  from  the 
specified  north.  The  vertical  offset  will  shift  the  location  to  the  south  if  positive,  north  if  negative; 

x  off  set,  which  shifts  the  text  a  horizontal  distance  in  pixels  from  the  specified  east  The  horizontal 
offset  will  shift  the  location  east  if  positive,  west  if  negative; 

whether  or  not  the  text  should  be  opaque  to  vectors.  Entering  no  to  the  opaque  option  will  allow  the 
user  to  see  any  vectors  which  go  through  the  text’s  background  bat.  Otherwise,  they  will  end  at  the 
box’s  edge. 

This  example  would  place  the  text  SPEARFISH  LAND  COVER  at  the  coordinates  E650000 
N7365000.  The  text  would  be  a  total  of  3  pixels  wide  (2  pixels  of  red  text  and  1  pixel  black  highlight), 
have  a  white  background  enclosed  in  a  red  bat,  and  be  500  meters  in  size.  The  lower  right  comer  erf 
the  text  would  be  centered  over  the  coordinates  provided.  All  vectors  on  the  map  would  stop  at  the 
border  of  this  text. 

EXAMPLE:  text  650000  7365000  SPEARFISH  LAND  COVER 
font  romand 
color  red 
width  2 
bcoior  black 
hwidth  1 

background  white 
border  red 
rfze  500 


GRASS  4.0  (Summer  1991) 


U  S.  Army  CERL 


213 


p.map 


GRASS  Reference  Manual 


p.inap 


ref  lower  left 

opaque  y 
end 


vector 

Selects  a  vector  map  layer  for  output. 

USAGE:  vector  vectormap|  list 

color  color 
width  # 
heal  or  color 
hwidth  # 
masked  [y|  n] 
style  0-9 
end 

The  user  can  specify  the  color  erf  the  vectors;  the  width  erf  the  vectors  lines  in  pixels;  the  highlight 
color  (hcolor)  for  the  vector  lines;  the  width  erf  the  highlight  color  (hwidth)  in  pixels;  whether  ex'  not 
the  raster  map  layer  is  to  be  masked  by  the  current  mask  (see  manual  entry  rjnask  for  more 
information  on  the  mask);  and  the  line  style.  The  line  style  allows  the  vectors  to  be  dashed  in  efifferent 
patterns  and  colors.  Tins  is  done  by  typing  a  series  of  numbers  (0-9)  in  a  desired  sequence  or  pattern. 
Colors  for  the  numbers  (1-9)  can  be  assigned  using  the  color  instruction.  Blanks  and  non-digit 
characters  are  recognized  as  0’s.  Using  0  would  allow  the  colors  of  the  raster  map  layer  (or  the 
background  color  if  no  raster  map  layer  was  selected)  to  show  through. 

This  example  would  paint  a  map  of  the  vector  map  layer  named  streams.  These  streams  would  be  a 
total  of  3  pixels  wide  (the  inner  two  pixels  blue  and  the  outer  highlight  pixel  white).  The  map  would 
not  show  streams  outside  erf  the  current  mask. 

EXAMPLE:  vector  streams 

color  blue 
width  2 
hcolor  white 
hwidth  1 
masked  y 
cud 

This  example  would  paint  a  map  of  die  vector  map  layer  roads.  These  roads  would  be  2  pixels  wide 
and  would  be  dashed  blank-black-red  (the  blank  areas  would  show  what  lies  under  the  roads).  This  map 
would  show  roads  inside  and  outside  of  the  current  mask. 

EXAMPLE:  vector  roads 

width  2 
style  001 122 
color  1  black 
color  2  red 
masked  n 
end 


verbose 

Changes  the  amount  erf  talking  p.map  will  do. 
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USAGE:  verbose  [0|1|2] 

A  higher  value  implies  more  chatter.  Hie  default  is  2.  This  example  sets  the  amount  erf  chatter  to  a 
minimum. 

EXAMPLE:  verboee  0 


end 

Terminates  input  and  begin  painting  the  map. 

USAGE:  end 

NAMED  COLORS 

The  following  are  the  colors  that  are  accepted  by  pjnap : 

aqua  black  Hue  brown  cyan  gray  green  grey  indigo  magenta  orange  purple  red  violet  white  yellow 
ICONS  VS.  PATTERNS 

Icons  and  patterns  as  used  in  p.map  are  not  the  same  thing.  Patterns  are  defined  and  are  normally  used 
to  cover  those  extended  areas  covered  by  a  raster  map  layer  category.  A  pattern  will  repeat  above, 
below  and  adjacent  to  itself.  Icons  are  used  to  represent  a  single  point. 

Patterns  are  supported  directly  within  pjnap  using  the  defpat  instruction,  while  icons  must  be  created 
using  the  pJcons  program. 
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EXAMPLE  p.map  INPUT  FILE 

The  following  is  an  example  of  a  pjnap  script  file.  The  file  has  been  named  spear. soils.  For  the 
purposes  of  illustration,  the  file  is  in  two  columns.  This  script  file  can  be  entered  at  the  command  line: 

pjnap  input  =spear  .soils 


raster  soils 
rector  streams 
color  Hue 
width  2 
hcolor  white 
hwidth  1 
nasked  y 
cad 

rector  roads 
width  2 
style  001122 
color  1  black 
color  2  red 


labels  town.names 
region  subregion 
color  white 
width  2 
end 

grid  10000 
color  green 
anmbers  2  red 
end 
outline 
color  Mack 
end 

colortable  y 
comments 

This  is  a  comment 

end 

scale  1:25000  end 
setcolor  6,8,9  white 
set  col  or  10  green 


(cont.) 
defpat  <fiag 
000001 
00001 
0001 
001 
01 
1 

color  1  red 
end 

setpat  4  diag 

text  608000.00  3476004.73  SPEARFISH  SOILS  MAP 

color  red 
width  2 
hcolor  black 
hwidth  1 

background  white 
border  red 
size  500 
ref  lower  left 

opaque  y 
end 

line  606969.73  3423092.91  616969.73  3423092.91 
color  yellow 
width  2 
opaque  yes 
end 

point  40%  60% 
color  purple 
icon  diamond 
size  2 
masked  n 

end 


INTERACTIVE  MODE 

If  the  user  simply  enters  p.map  without  arguments,  then  a  single  prompting  session  occurs.  Some,  but 
not  all  of  the  non-interactive  requests  are  available  at  this  level. 


SEE  ALSO 

p.chart,  p.icons,  p. labels,  prelect 

AUTHOR 

Michael  Shapiro,  US.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

p.ppm  -  Reads  portable  pixinap  (ppm)  files  created  by  PPM  utilities. 

(GRASS  Paint/Print  Program) 

SYNOPSIS 

p.ppm 
p.ppm  help 

p.ppm  [-f]  [input  =name] 

DESCRIPTION 

This  program,  p.ppm,  reads  a  user-specified  porta  We  pixmap  (ppm)  file  and  outputs  it  to  the  currently 
selected  printer  (see  prelect).  The  input  ppm  file  should  be  one  that  has  been  created  using  the  PPM 
utilities  developed  by  Jeff  Poskanzer.  'Ihese  utilities  can  import  various  image  formats  (including  SUN 
raster,  X  Windows  pixmaps,  and  others)  into  the  PPM  formats  ppm  (color  pi x maps),  pgm  (grey  scale 
maps),  and  pbm  (biack  and  white  bit  maps). 

If  the  image  doesn’t  fit  the  output  device,  it  won’t  get  printed.  If  you  want  the  image  printed  (but 
clipped),  use  the  p.ppm  -f  option,  or  scale  the  input  using  ppmscale  or  rotate  the  image  using 
ppmrotate  (if  it  will  fit  that  way  —  otherwise  you  might  have  to  scale  it  as  well).  If  the  image  doesn’t 
fit,  p.ppm  will  tell  you  w'hat  scaling  value  to  enter  to  ppmscale  that  will  make  it  fit. 

EXAMPLES 

If  the  user  is  running  GRASS  on  a  SUN  machine,  the  following  command  could  be  used  to  send  a 
monitor  screen  image  to  the  printer: 

screcndump  |  rasttoppm  |  p.ppm 

If  you  are  running  suntools,  the  user  might  type: 

sleep  10;  screcndump  |  rasttoppm  |  ppmrotate  90  |  p.ppm 

The  UNIX  sleep  command  allows  you  time  to  arrange  the  frames  before  the  screen  dump  starts.  The 
ppmrotate  is  usually  needed  because  the  SUN  screens  are  wider  than  thev  are  long  (and  wider  than 
1024  pixels  -  which  is  the  width  of  most  of  our  painters). 

If  you  are  naming  X,  the  user  might  typre: 

xwd  |  xwdtoppm  |  ppmrotate  90  |  p.ppm 

NOTES 

This  program  only  supports  the  ppm  binary  format  (P6). 

Maximum  color  level  is  255.  If  the  pjpin  file  has  more  color  levels,  use  ppmcscale  to  reduce  the 
number  of  colors. 

No  scaling  is  done.  Use  ppmscale  to  change  image  size. 

No  rotation  is  done.  Use  ppmrotate  to  rotate  the  image. 

SEE  ALSO 

See  also: 

The  PPM  utilities 

ppmrotate  (rotates  ppmi  images), 

ppmscale  (scales  ppm  images  for  painting), 

rasttoppm  (converts  a  SUN  raster  file  to  ppm  format),  and 

xwdtoppm  (converts  an  X  Windows  dump  file  to  ppmi  format). 

The  SUN  p>rogram  screendump  (dumps  tiro  image  on  the  color  graphics  monitor  into  a  file  in  SUN 
raster  file  fonnat). 
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The  X  pr jg ran  xwd  (dumps  the  image  in  an  X  window  into  a  file  in  X  window  chimp  [xwdj  format). 
The  GRASS  programs  d.save,  d.savescreen.  pjnap,  p^^lect,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
This  program  uses  the  PPM  utilities  developed  by  Jeff  Poskanzer. 
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NAME 

p.screen  -  Prints  a  graphics  monitor  display  image  file  that  has  been  saved  by  djavescreen. 

(GRASS  Paint /Print  Output  Program) 

SYNPOSIS 

p.screen 
p.screen  help 

p.screen  [-r]  input  -  name  [bg  =value)  [sca)e=va/ue[p|  i]] 

DESCRIPTION 

p.screen  prints  the  graphics  monitor  screen  image  file  created  by  djsavtscreen  to  a  color  printer. 

Flag: 

Select  black  and  white  reversal.  Whatever  is  specified  as  black  in  the  original 
graphics  monitor  display  image  is  printed  ("painted")  in  white,  and  whatever  was 
white  in  the  screen  image  is  printed  in  black. 

Name  of  a  file  containing  a  graphics  screen  image. 

C&ta  (category)  value  representing  the  background  color  Enables  user  to  set  the 
background  color  to  white  without  having  to  reveise  all  black  and  white.  For 
example,  -wO  will  set  color  0  to  white. 

scale  ^valuep  or  scale  -valuei 

Image  scaling  factor.  If  not  specified  ’-v  the  user,  the  graphics  monitor  screen 
image  is  scaled  to  fill  the  width  of  the  printer  (i.e.,  Ip,  1  panel  wide).  It  outputs 
the  graphics  monte*-  screen  'mage  at  me  ratio  of  1  image  pixel  to  # printer  pixels 
(i.e.,  4  will  print  the  graphics  monitor  screen  image  at  a  ratio  of  1  image  pixel  = 
4  printer  pixels),  fhis  a-  on  is  useful  if  the  resampling  of  the  screen  image  must 
be  controlled. 

Since  rescuing  often  entails  dropping  some  input  pixels  or  repeating  some  input 
pixels  more  often  than  others,  linear  elements  in  the  screen  image  may  be 
distorted.  This  effect  can  be  eliminated  by  specifying  1  as  the  scaling  factor. 

p  Outputs  the  graphics  monitor  screen  image  at  #  panels  wide  (i.e.,  3p  will 
print  the  graphics  monitor  screen  image  at  3  panels  wide). 

i  Outputs  the  graphics  monitor  screen  image  at  #  inches  wide  (i.e.,  83i 

will  print  the  screen  image  83  inches  wide). 

If  no  arguments  are  given  on  the  command  line,  the  user  will  be  prompted  for  the  input  file  name,  the 
background  data  value,  the  image  scaling  factor,  and  the  black-white  reversal  flag  setting. 

NOT  s 

lhe  input  file  to  p.screen  is  generated  by  the  program  d.savescreen.  Al  present,  d.savescreen  only 
exists  for  MASSCOMP  systems.  If  you  do  not  have  a  MASSCOMP,  you  probably  will  not  be  able  to 
save  screens  to  lie  painted  by  p screen. 

SEE  AI.SO 

d.savescreen,  p.chart,  p.map,  pjelect 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 


Parameters: 
input  = name 
bg  =value 
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NAME 

p. select  -  Selects  a  device  (printer)  for  (iRASS  hardcopy  output. 

(GRASS  Hardcopy  Output  Program) 

SYNOPSIS 

p. select 
p. select  help 

p.select  [Hpq[  [painter  =name] 

DESCRIPTION 

p.select  allows  the  user  to  select  the  device  for  GRASS  hardcopy  output.  The  user  must  select  a 
device  before  ninning  the  other  (iRASS  hardcopy  output  functioas  (e.g.,  p.map,  p. labels,  p.chart). 

COMMAND  LINE  OPTIONS 
Flags: 

-1  list  all  available  painters. 

-p  Print  name  of  currently  selected  painter. 

-q  Quietly  select  painter. 


Parameter: 

painter  =name  Name  of  painter  to  select. 

Options:  (this  will  be  a  list  of  available  hardcopy  output  devices,  and  also 
preview ,  the  user’s  graphics  monitor) 

INTERACTIVE  MODE 

If  the  user  runs  prelect  withrxit  specifying  program  arguments  on  the  command  line,  the  program  will 
prompt  the  user  for  the  name  of  a  hardcopy  output  device  to  select. 

SEE  ALSO 

p.chart,  p.labels,  pjnap 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r. aver  age  -  finds  the  average  of  values  in  a  values  map  within  areas  assigned  the  same  category  value 
in  a  user-specified  base  map. 

(GRASS  Raster  Program) 

SYNOPSIS 

leverage 
r .average  help 

r .aver age  [-c]  base  name  values  =name  result  =name 
DESCRIPTION 

r. average  calculates  the  average  value  of  data  contained  in  a  values  raster  map  layer  for  areas  assigned 
the  same  category  value  in  the  user-specified  base  raster  map  layer.  These  averaged  values  are  stored 
in  the  category  labels  file  associated  with  a  new  result  map  layer. 

The  values  to  be  averaged  are  taken  from  a  user-specified  values  map.  The  category  values  for  the 
values  map  will  be  averaged,  unless  the  -c  flag  is  set.  If  the  -c  flag  is  set,  the  values  that  appear  in  the 
category  labels  file  for  the  values  map  will  be  averaged  instead  (see  example  below). 

The  result  map  is  actually  a  reclass  erf  the  base  map  (see  r.redass),  and  will  have  exactly  the  same 
category  values  as  the  base  map.  The  averaged  values  computed  by  rutverage  are  stored  in  the 
result  map’s  category  labels  file. 

If  the  user  simply  types  r .aver age  on  the  command  line,  the  user  is  prompted  for  the  flag  setting  and 
parameter  values  through  the  standard  parser  interface  (see  parser  manual  entry). 

Alternately,  the  user  can  supply  all  needed  flag  settings  and  parameter  values  on  the  command  line. 
Fl»g: 

-c  Take  the  average  of  the  values  found  in  the  category  labels  for  die  values  map, 

rather  than  the  average  of  the  value  map’s  category  values. 


Parameters: 

baa*=name 


valnes=name 


result  =name 


An  existing  raster  map  layer  in  the  user’s  current  mapset  search  path.  For  each 
group  erf  cells  assigned  the  same  category  value  in  die  base  map,  the  values 
assigned  these  cells  in  the  values  map  will  be  averaged. 

An  existing  raster  map  layer  containing  the  values  (in  the  form  of  cell  category 
values  or  cell  category  labels)  to  be  averaged  within  each  category  of  the  base 
map. 

The  name  of  a  new  map  layer  to  contain  program  output  (a  reclass  of  the  base 
map).  Averaged  values  will  be  stored  in  the  result  map’s  category  labels  file 
under  the  user’s  SliXATION/cats  directory. 
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EXAMPLE 

Assume  that  farms  is  a  map  with  seven  farms  (i.e.,  seven  categories),  and  that  soils. Kfactor  is  a  map 
erf  soil  K  factor  values  with  the  following  category  (ile: 

category  category 

value _ label 

0  no  soil  data 

1  0.10 

2  0.15 

3  0.17 

4  020 

5  024 

6  028 

7  032 

8  037 

9  0.43 

Then 

r .average  -c  base  farms  valnes=soils.Kfactar  result  =K.by Jarm 

will  compute  the  average  soil  K  factor  for  each  farm,  and  store  the  result  in  the  resultant  map 
Kby.farm,  which  will  be  a  reclass  of  farms  with  category  labels  as  follows  (example  only): 

category  category 

value _ label 

1  0.1023 

2  0.1532 

3  0.172 

4  03872 

5  0.003 

6  028 

7  02345 


NOTES 

The  c  option  requires  that  the  category  label  for  each  category  in  the  values  map  be  a  valid  number, 
integer,  or  decimal.  To  be  exact,  if  the  first  item  in  the  label  is  numeric,  then  that  value  is  used. 
Otherwise,  zero  is  used.  The  following  table  covers  all  possible  cases: 

category  label  value  used  by  @ 

.12  0.12 

.80  KF  0.8 

no  data  0 

(This  operator  is  very  similar  to  the  @  operator  in  r.mapcalc,  and  the  user  is  encouraged  to  read  the 
manual  entry  for  rjnapcalc  to  see  how  it  works  there.) 

The  user  should  use  the  results  of  r.average  with  care.  Since  this  utility  assigns  a  value  to  each  cell 
which  is  based  on  global  information  (i.e.,  information  at  spatial  locations  other  than  just  the  location  of 
the  cell  itself),  the  resultant  map  layer  is  only  valid  if  the  geographic  region  and  mask  settings  are  the 
same  as  they  were  at  the  time  that  the  result  map  was  created. 

Results  are  affected  by  the  current  region  settings  and  mask. 
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SEE  ALSO 

g.region,  r.cais,  r. clump,  r.describe,  rjmpcalc,  r.mask,  rjrfilter,  rjteighbors,  rseclass,  rjtats, 
and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r. basins. fill  -  Generates  a  raster  map  layer  showing  watershed  subbasins. 

(GRASS  Raster  Program) 

SYNOPSIS 

rirasinsJill 
rJbasinsJill  help 

riraain&Jill  numb er=value  c  map  name  tjnap  =name  result  name 
DESCRIPTION 

r.basins.fill  generates  a  raster  map  layer  depicting  subbasins,  based  on  input  raster  map  layers  for  the 
coded  stream  network  (where  each  channel  segment  has  been  "coded"  with  a  unique  category  value) 
and  for  the  riches  within  a  given  watershed.  The  raster  map  layer  depicting  ridges  should  include  the 
ridge  which  define*;  the  perimeter  of  the  w  atershed.  The  coded  stream  network  can  be  generated  as  part 
of  the  r .watershed  program,  but  the  map  layer  of  ridges  will  need  to  be  created  by  hand,  either  through 
digitizing  done  in  v. digit,  or  through  the  on-screen  digitizing  option  accessible  within  d.display  or 
d.digit. 

The  resulting  output  raster  map  layer  will  code  the  subbasins  with  category  values  matching  those  of 
the  channel  segments  passing  through  them.  A  user-supplied  number  of  passes  through  the  data  is 
made  in  an  attempt  to  fill  in  these  subbasins.  If  the  resulting  map  layer  from  this  program  appears  to 
have  holes  within  a  subbasin,  the  program  should  be  rerun  with  a  higher  number  of  passes. 

The  user  can  run  r.basins.fill  either  interactively  or  non-interactively.  If  the  aser  simply  types 
rJrasinsJill  without  other  arguments  on  the  command  line,  the  program  will  prompt  the  user  for  the 
needed  parameters  using  the  standard  GRASS  parser  interface  (see  manual  entry  for  parser). 

If  the  user  wishes  to  run  the  program  non-interactively,  the  following  parameter  values  must  be 
specified  on  the  command  line: 


Parameters: 
number  =value 
cmap  -name 
t  map  name 
result  name 


Ihe  number  of  passes  to  be  made  through  the  dataset. 
The  coded  stream  network  file  name. 

Ihe  thinned  ridge  network  file  name. 

The  resultant  watershed  partition  file  name. 


NOTES 

The  current  geographic  region  setting  is  ignored.  Instead,  the  geographic  region  for  tire  entire  input 
stream’s  map  layer  is  used. 


SEE  ALSO 

See  Appendix  A  of  the  GRASS  Tutorial:  r.watershed  for  further  details  on  the  combined  use  of 
r.basins.fill  and  r.watershed. 

d.digit,  d.display,  r.watershed,  v. digit,  and  parser 

AUTHORS 

Dale  White,  Dept,  of  Geography,  Ihe  Pennsylvania  State  University 
Larry  Band,  Dept,  of  Geography,  University  of  Toronto,  Canada 
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NAME 

r.binfer  -  Bayesian  expert  system  development  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

rJbinfer 
rJbinfer  help 

rJbinfer  [-v]  input  name  [output  name] 

DESCRIPTION 

r.binfer  is  an  expert  system  shell  containing  an  inference  engine  based  on  Bayesian  statistics  (reasoning 
from  past  experience).  It  is  designed  to  assist  human  experts  in  a  field  develop  computerized  expert 
systems  for  land  use  planning  and  management.  These  expert  systems  are  designed  to  aid  non-experts 
make  decisions  about  land  use. 

In  Bayesian  expert  system  programs  like  rJbinfer,  the  system  bases  the  probable  impacts  of  a  future 
land  use  action  on  the  conditional  probabilities  about  the  impact  of  similar  past  actions. 

COMMAND  LINE  OPTIONS 
Flags: 

-v  Run  verbosely,  displaying  messages  on  debugging  output  to  standard  output. 

Includes  a  listing  erf  the  symbol  table  used  by  rJbinfer. 

Parameters: 

input  =name  Name  of  an  existing  file  containing  analysis  instructions. 

output=name  Name  to  be  assigned  to  the  file  to  contain  program  output. 

Default:  binfer.out 

Using  appropriate  r.binfer  syntax,  the  human  expert  structures  an  input  knowledge/control  script  with 
an  appropriate  combination  of  map  layer  category  values  (GRASS  raster  map  layers  that  contain  data 
on  soil  texture,  slope,  density,  etc.)  and  attributes  relevant  to  decision-making  (eg.,  rainfall, 
temperature,  season,  subjective  judgement,  etc.).  Options  exist  for  specifying  a  user  interface  and  a 
data  base  containing  prior  and  conditional  probabilities  necessary  to  infer  the  value  of  a  goal  attribute. 
The  expert  also  specifies  the  format  for  display  erf  end  results  (raster  map  layers)  in  the  input  script. 
New  raster  map  layers  -  one  for  each  possible  inferred  attribute  value  —  are  created  that  contain  the 
probability  of  the  inferred  attribute  value  occurring  in  each  grid  cell. 

Alternately,  a  single  new  map  layer  called  rJbinfer  (or  whatever  output  name  is  specified  by  the  user) 
is  also  output.  This  map  shows,  for  each  grid  cell,  the  inferred  attribute  value  that  has  the  highest 
probability  of  occurring  in  each  grid  cell,  given  the  values  of  the  input  raster  map  layer  and  contextual 
attributes. 

r.binfer  scripts  are  typed  into  a  file  by  the  user  using  a  system  editor  like  vi,  and  then  input  to  rJbinfer 
as  the  input  file  named  on  the  command  line.  For  a  complete  description  erf  the  input  syntax,  see  the 
document  GRASS  Tutorial:  rbinfer  (forthcoming).  For  example  rbinfer  scripts  see  the  EXAMPLES 
section  below.  The  results  are  used  to  generate  the  new  raster  map  layers  in  the  user’s  current  mapset. 

As  stated  above,  rbinfer  scripts  contain  descriptions  of  two  types  of  input  attributes.  The  map  layer 
type  attributes  are  actual  GRASS  raster  map  layers,  with  the  values  defined  to  be  ranges  of  the 
categories  within  that  raster  map  layer.  For  example,  if  the  user  chooses  slope  as  one  of  the  layer 
attributes,  the  possible  values  for  the  slope  attribute  might  be  the  following: 

flat  (slopes  between  0  and  5  degrees) 

low  (slopes  between  6  and  10  degrees) 

medium  (slopes  between  11  and  30  degrees) 
steep  (slopes  greater  than  31  degrees) 
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I  he  contextual  attributes  are  those  that  do  not  represent  raster  map  layers,  but  rather,  information  that 
reflects  criteria  relevant  to  the  specific  decision  being  contemplated,  bor  example,  if  the  user  chooses 
"niinfall  amount"  as  one  of  the  contextual  attributes,  possible  values  assigned  to  the  "rainfall  amount" 
attribute  might  be  the  following: 

low  (rainfall  amounts  less  than  1  inch) 

medium  (rainfall  amounts  between  1  and  3  inches) 
high  (rainfall  amounts  greater  than  3  inches) 

The  inferred  attribute  values  are  specified  altmg  with  a  prior  probability  and  a  table  of  conditional 
probabilities  that  indicate  the  probability  of  that  inferred  attribute  value  occurring  given  that  an  input 
attribute  value  has  occurred. 

r.binfer  will  determine  the  value  of  contextual  attributes  by  prompting  the  user  for  input.  It  will  then 
open  each  of  the  raster  map  layers  corresponding  to  each  map  layer  attribute,  r.binfer  then  determines 
the  values  for  all  map  layer  attributes  in  each  grid  cell.  Using  the  conditional  probability  tables,  the 
prior  probabilities,  and  Baves’  theorem,  r.binfer  calculates  the  output  probabilities  for  each  inferred 
value  and  writes  its  probability  of  occurrence  as  a  percentage.  It  also  determines  which  value  is  most 
likely  to  occur  in  that  cell  and  writes  that  to  the  output  file  name. 

EXAMPLES 

The  two  sample  scripts  shown  below  illustrate  only  the  use  of  r.binfer  to:  (1)  estimate  the  probability 
that  an  avalanche  will  occur,  and  (2)  infer  the  probability  of  finding  pine  mountain  beetles,  at  each  cell 
across  a  landscape,  giv  en  the  input  map  layer  attributes  shewn  lielow.  The  author  makes  no  claims  as 
to  the  correctness  of  using  these  criteria  to  infer  either  event. 


Some  Notes  on  Script  Constniction. 


1.  No  Data  (  or  w  hat  to  do  with  category  zero). 

If  category  zero  is  excluded  front  the  ranges  of  any  layer 
attribute  value,  it  is  treated  as  "no  data"  and  the 
resulting  probability  ;utd  combined  maps  will  reflect  this. 

Otherwise,  category’  zero  is  treated  just  like  any  other  cell  value. 

2.  Category  ranges  for  layer  attributes. 

Ihe  category  ranges  ;tre  specified  using  r.recluss  rules. 

For  example,  a  value  list  for  slope  might  look  like  this: 

(flat  [0  1  thm  31,  gentle  [4  thm  SI.  nuxlerate  [9  tlmi  151, 
other  1 16  thru  S9|). 

3.  Question  Attachments. 

Question  altaclimcnts  can  lx.'  supplied  for  and  context  attribute  or 
attribute  value.  If  names  are  chosen  cleverly  ,  the  default  menu 
should  be  sufficient. 

4.  Determinant  1 1st. 


.'o 
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At  tbs  time  the  determinant  list  serves  no  real  purpose. 
Planned  extensions  to  binfer  will  make  use  of  this  list, 
so  just  don’t  use  it  for  new. 

5.  Probabilities. 

The  conditional  probability  table  is  very  important,  try  to 
be  sure  of  its  accuracy. 
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# 

#  Filename:  avalanche.binfer 

# 

#This  is  a  r.binfer  script  that  infers  the  probability  of  an 

#  avalanche  occurring,  given  the  values  of  the  input  attributes. 

# 

#NGTE-  Execute  r.binfer  as  follows: 

#  r.binfer  avalanche Jtinfer  [ output  =nome] 

#  If  the  user  does  not  specify’  an  output  file  name, 

#  the  combined  map  will  be  named  binfer. 

# 

#  Script  file  output  keywords: 

# 

#  CombinedMap  (Colortable)  -  assigns  the  combined  map  the  given  colortabie. 

#  NoCombinedMap  -  only  generates  probability  maps 

#  (one  for  each  inferred  attribute  value). 

#  NoProbabilityMaps  -  only  generates  combined  map. 

#  (Colortable)  can  be  any  of  the  following  keywords: 

#  Aspect  -  aspect  colors, 

#  Grey  .Gray  -  grey  scale, 

#  Hsto  -  histogram  stretched  grey  scale, 

#  Rainbow  -  rainbow  colors, 

#  Ramp  -  color  ramp  (default), 

#  Random  -  random  colors, 

#  RYG  -  red  yellow  green, 

#  Wave  -  color  wave. 

# 

# 

if  Start  layer  attrilxite  section. 

# 

layer: 

#' 

#  I  ayer  attribute  ffl  is  aspect 

# 

aspect: 

# 

#  all  southern  exjxisures  =  1 . 

#  all  eastern  exposures  =  2. 

it  all  western  exposures  =  3. 

if  all  northern  exposures  =  4. 

#  all  others  =  0. 

tt 

(south)  16  thm  22].east|22  23  1  thru  4), west)  1 1  thm  1 5 1 , 
north)?  thm  10)). 

# 

ft  I  ayer  attribute  itl  is  slope 

it 

slope: 

it 

it  low  -  0  to  9  degrees 
it  in<  derate  10  19  degrees 

it  steep  -  20  -  29  degrees 
"  severe  -  30  -  >SN  degrees 
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(low[l  thru  10],moderate{ll  thru  19]^steep(20  thru  30],seve*e(31  thru  89]). 

% 

#End  erf  layer  section 
# 

#  Start  context  section 

# 

context: 

# 

# Contextual  attribute  #L  is  temperature 

#NOTE:  A  menu  will  be  constructed  using  the  attribute  name  and 

#  the  names  erf  the  attribute  values. 

#  The  user  will  be  prompted  to  enter  his  choice. 

# 

temperature: 

(freezing  ,cold,warm,hot). 

# 

# Contextual  attribute  18  is  snowfalLamt 

#NOTE:  A  menu  will  be  constructed  using  the  question  attachments 

#  supplied  here. 

#  The  user  will  be  prompted  to  enter  his  choice. 

# 

snowfalLamt: 

(a  {question  "Less  than  one  foot."}, 
b  {question  "Between  a  foot  and  four  feet."}, 
c  {question  "More  than  four  feet."}) 

{question  "How  much  snow  has  accumulated  ?’}. 

% 

#End  erf  context  section. 

# 

#  Start  inferred  section 

# 

inferred: 

# 

# Inferred  attribute  is  avalanche. 

# 

avalanche: 

# 

# Inferred  attribute  value  "high.” 

#  A  colortable  of  Ramp  will  be  assigned  (default). 

# NOTE:  Prior  probability,  and  conditional  probabilities  are  given  in 

#  this  section. 

# 

(high  <020> 

[0.10, 0.50  0200.20; 
0.05,0.15p20P^0; 
O.8O,O.15jOjOO0.G5; 

0.05, 035 jO.60;)  , 

# 

#  Inferred  attribute  value  "moderate." 

#  A  colortable  of  Grey  will  be  assigned. 
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# 

moderate  Grey  <030> 

[0.15 ,035 />25/)25; 
0.10,020/)20/).50: 
0.75,020/).00/).05: 
0.05,035,0.60;]  , 

# 

#  Inferred  attribute  value  "low." 

#Acolortable  of  Rainbcw  will  be  assigned. 

# 

low  Rainbow  <050> 

[0.25,025,025,0.25: 
025 ,025/) 25/)  .25 
030,030/).10/).10: 
0.10,0.40,050;]  ). 

% 

#End  of  inferred  section. 

#End  of  avalanche.binfer  script. 
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# 

#Rlename:  bugsbinfer 
# 

#This  is  a  r.binfer  script  that  infers  the  probability  of  finding 
#pine  mountain  beetles,  given  the  input  layer  attributes  below. 

#NOTE:  Execute  rJbinfer  as  follows: 

#  bi lifer  bugsJbinfer  [  output  =name  ] 

#  if  the  user  does  not  specify  an  output  name,  the  combined  map 

#  will  be  named  binfer. 

# 

#  Script  file  output  keywords: 

# 

#  Combi nedMap  (Colortable)  -  assigns  the  combined  map  the  given  colortable. 

#  NoCombinedMap  -  only  generates  probability  maps 

#  (one  for  each  inferred  attribute  value). 

#  NoProbability Maps  -  only  generates  combined  map. 

#  (Colortable)  can  be  any  of  the  following  keywords: 

#  Aspect  -  aspect  colors, 

#  Grey, Gray  -  grey  scale, 

#  Hsto  -  histogram  stretched  grey  scale, 

#  Rainbow  -  rainbow  colors, 

#  Ramp  -  color  ramp  (default), 

#  Random  -  random  colors, 

#  R.YG  -  red  yellow  green, 

#  Wave  -  color  wave. 

# 

# Choose  the  combined  map  colortable  to  be  a  color  wave 
CombinedMap  Wave 
# 

#  Start  layer  attribute  section. 

# 

layer: 

# 

#Layer  attribute  tfi  is  slope 
# 

slope: 

# 

# 

(low[l  thru  10],moderale[ll  12  13  14  thru  20],steep(21  thru  30],severe[31  thru  89]). 
# 

#  Layer  attribute  &  is  aspect 

# 

aspect: 

# 

# 

(south[16  thru  22],east(22  23  1  thru  4],west[ll  thru  15], 
north{5  thru  10]). 

# 

#  Layer  attribute  4S  is  vegcwer 

# 

veg  cover: 

(other]  1  thru  2]  ,coniferous[3],deciduous[4],mixed[5], disturbed] 6]). 

# 


r.binfer 


GRASS  4.0  (Summer  1991) 


U.S.  Army  CERL 


231 


r.binfcr 


GRASS  Reference  Manual 


r.binfcr 


#  Laver  attribute  #t  is  (forest)  density 

# 

density: 

(nonforest[  1  ]  ,sporse[  2  ]  .moderate]  3 )  ,dcnse[4]). 

O/ 

/o 

#Hnd  of  layer  S  '  tion. 

# 

#  Start  inferred  section 

# 

inferred: 

# 

#  Inferred  attribute  is  bugs 

# 

bugs. 

# 

#  Inferred  attribute  value  "bugs." 

#  A  colortable  of  Ramp  will  be  assigned  (default). 

#NOTE:  Prior  probability,  and  conditional  probabilities  are  given  in 

#  this  section. 

# 

(bugs  <020> 

[0.124,0.416,0371,0.090;  #conditiortals  corresponding  to  slope, 
0.180,0292,0292,0239;  #myaspcct, 

0 .01 1 ,0 .798 ,0 .022 ,0 .1 69 ,0.0;#  vegcover, 

0202,0326,0213,0258;],  #and  deasity  (one  per  valiu ' 


# 

#  Inferred  attribute  value  "nobugs." 

#  A  colortable  of  Rainbow  will  be  assigned. 

# 

nobugs  Rainbow  <0.80:?- 

[0.404,0.416,0.157,0.011; 

0.225,0281,0281,0225; 

0.281 ,0.427,0.135,0.056,0.0; 
0384,0.112,0202,0.112;]). 

% 

#Fnd  of  inferred  section. 

#Fnd  of  bugs.binfer  script. 


SEE  ALSO 

GRASS  Tutorial:  r.binfer  (forthcoming). 

AUTHOR 

Kurt  llueliler,  Purdue  University 
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NAME 

r.buffer  -  Creates  a  raster  map  layer  showing  buffer  zones  surrounding  cells  that  contain  non-zero 
category  values. 

(GRASS  Raster  Program) 

SYNOPSIS 

rJraffer 
r  .buffer  help 

r .buffer  input  =name  output  =name  distances=vo/ue[,va/ue,...]  [units  =name] 

DESCRIPTION 

r.buffer  creates  a  new  raster  map  layer  showing  buffer  (aka,  "distance"  or  "prcKimity")  zones  around  all 
cells  that  contain  non-zero  category  values  in  an  existing  raster  map  layer.  The  distances  of  buffer 
zones  from  cells  with  non-zero  category  values  are  user-chosen.  Suppose,  for  example,  that  you  want 
to  place  buffer  zones  around  roads.  This  program  could  create  the  raster  map  layer  shown  below  on  the 
right  based  on  road  information  contained  in  the  raster  map  layer  shown  on  the  left. 


OOOOOOOOOOOOOOOOOfXfOOOOO 
111000000000000000000000 
000111111111100000000000 
000000001000011 100000000 
000000001000000011111111 
000000001000000000000000 
000000001000000000000000 
000000001000000000000000 
00000000 1 000000000000000 
(Category  0:  No  roads 
Category  1:  Roads 


1 1 1122222222222222333333 
000111111111112222222222 
111000000000011112222222 
221111110111100011111111 
2222222101221 1 1100000000 
322222210122222111111111 
333332210122222222222222 
333332210122332222222222 
333332210122333333333333 
Category  0:  Road  location 
Category  1:  Buffer  Zone  1  around  roads 
Category  2:  Buffer  Zone  2  around  roads 
Category  3:  Buffer  Zone  3  around  roads 


INTERACTIVE  PROCRAM  USE 

The  user  can  run  the  program  interactively  by  simply  typing  r -buffer  without  program  arguments  on 
the  command  line.  lire  program  then  prompts  the  user  for  parameter  values. 

(1)  You  arc  requested  to  identify  the  existing  raster  map  layer  from  which  distance-front  calculations 
shall  lie  based,  and  a  name  (of  your  choice)  for  the  new  raster  map  layer  which  will  contain  the  results. 

(2)  '11  ten,  identify  the  units  of  measurement  in  which  buffer  (distance)  zones  are  to  be  calculated,  and 
the  distance  of  each  Ixiffer  zone  from  each  non-zero  cell  in  the  input  map.  The  user  has  the  option  of 
identifying  up  to  60  continuous  zones.  The  zones  are  identified  by  specifying  the  upper  limit  of  each 
desired  zone  (r.buffer  assumes  that  0  is  the  starting  point).  ("Continuous"  is  used  in  the  sense  that  each 
category  zone’s  lower  value  is  the  previous  zone’s  upper  value.  The  first  buffer  zone  always  has 
distance  0  as  its  lower  bound.)  Distances  can  be  entered  in  one  of  four  units:  meters,  kilometers, 
feet,  and  miles. 


(3)  last,  calculate  distances  from  cells  containing  user-specified  category  values,  using  the  "fromceH” 
method.  [The  "fromceH"  inethod  goes  to  each  cell  that  contains  a  category  value  from  which  distances 
;irc  to  lx-  calculated,  and  draws  tire  requested  distance  rings  around  them.  This  method  works  very  fast 
when  there  arc  few  cells  containing  the  category  values  of  interest,  but  works  slowly  when  there  are 
numerous  cells  containing  the  category  values  of  interest  spread  throughout  the  area.] 

Ihe  r.buffer  program  now  nuts  the  [irocess  in  "background”  and  returns  keyboard  control  to  the  user. 
These  processes  can  occasionally  take  up  to  an  hour  or  more  to  finish;  however,  because  they  run  in 
ihe  background,  you  ;ire  free  to  do  other  things  with  the  computer  in  the  interim. 
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NON -INTER  ACTIVE  PROGRAM  USE 

The  user  can  run  r. buffer  specifying  all  parameter  values  on  the  command  line,  using  the  form: 
r .buffer  input  name  output  name  distances=va/ue[,vaiue,...]  |units=/uj/nej 


Parameters: 

input  =name  The  name  of  an  existing  raster  map  layer  whose  non- zero  category  value  cells  are 

to  be  surrounded  by  buffer  zones  in  the  output  map. 

output  ^name  The  name  assigned  to  the  new  raster  map  layer  containing  program  output.  The 
output  map  will  contain  buffer  zones  at  the  user-specified  distances  from  non¬ 
zero  category  value  cell  in  the  input  map. 

distances=vu/ue[  yalue,...} 

The  distance  of  each  buffer  zone  from  cells  having  non- zero  category  values  in 
the  input  map. 

units=nnme  The  unit  of  measurement  in  which  distance  zone  values  are  to  be  calculated. 

Possible  choices  for  name  are:  meters ,  kilometers,  feet,  and  miles  The  default 
units  used,  if  unspecified  by  the  user,  are  meters. 

EXAMPLE 

In  the  example  below,  the  buffer  zones  would  be  (in  the  default  units  of  meters):  0-10,  11-20,  21-30, 
31-40  and  41-50. 

Format: 

r -buffer  input  name  output  name  distances=va/ue[ , value,...]  [units=namej 

Example: 

r. buffer  input  =map.in  output  -map. out  distances-l 0,20,30 ,40,50  units  -meters 

NOTES 

r. buffer  measures  distances  from  center  of  cell  to  center  of  cell  using  Euclidean  distance  measure  for 
planimetric  databases  (like  UTM)  and  using  ellipsoidal  geodesic  distance  measure  for  latitude/longitude 
databases. 

r. buffer  calculates  distance  zones  from  all  cells  having  non-zero  category  values  in  the  input  map.  If 
tlie  user  wishes  to  calculate  distances  from  only  selected  input  map  layer  category  values,  the  user 
should  run  (for  example)  r.reclass  prior  to  r.buffer,  to  reclass  all  categories  from  which  distance  zones 
are  not  desired  to  be  calculated  into  category  zero. 

SEE  ALSO 

r.region,  r.mapcalc,  r.reclass 
AUTHORS 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
James  Westervclt,  U.S.  Army  (Construction  Engineering  Research  laboratory 
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NAME 

r.cats  -  Prints  category  values  and  labels  associated  with  user-specified  raster  map  layers. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.cats 
r.cats  help 

rxats  map  name  [eats=range[/ange,...]]  [ tn=character  | space  | tab) 

DESCRIPTION 

r.cats  prints  the  category  values  and  labels  for  the  raster  map  layer  specified  by  iaap=name  to  standard 
output. 

The  user  can  specify  all  needed  parameters  on  the  command  line,  and  run  the  program  non- 
interac  lively.  If  the  user  does  not  specify  any  categories  (eg.,  using  the  optional 
cats=range[, range,...]  argument),  then  all  the  category  values  and  labels  for  the  named  raster  map 
layer  that  occur  in  the  map  are  printed.  The  entire  map  is  read,  using  r. describe,  to  determine  which 
categories  occur  in  the  map.  If  a  listing  of  categories  is  specified,  then  the  labels  for  those  categories 
only  are  printed.  The  cats  may  be  specified  as  single  category  values,  or  as  ranges  of  values.  The  user 
may  also  (optionally)  specify  that  a  field  separator  other  than  a  space  or  tab  be  used  to  separate  the 
category  value  from  its  corresponding  category  label  in  the  output,  by  using  the 
ts^character  \ space  \ tab  option  (see  example  belcw).  If  no  field  separator  is  specified  by  die  user,  a 
tab  is  used  to  separate  these  fields  in  the  output,  by  default. 

The  output  is  sent  to  standard  output  in  the  form  of  one  category  per  line,  with  the  category  value  first 
on  the  line,  then  an  ASCII  TAB  character  (or  whatever  single  character  or  space  is  specified  using  the 
fs  parameter),  then  the  label  for  the  category. 

If  the  user  simply  types  rusts  without  arguments  on  the  command  line  the  program  prompts  the  user 
for  parameter  values  using  the  standard  GRASS  parser  interface  described  by  parser. 

EXAMPLES 

rxats  map=soils 

prints  the  values  and  labels  associated  with  all  of  the  categories  in  the  soils  raster  map  layer; 

rxats  map-soils  cats— 10,12,15-20 

prints  only  the  category  values  and  labels  for  soils  map  layer  categories  10, 12,  and  15  through 
20;  and 

rxats  map=soils  cats  !0,20  fs=  : 

prints  the  values  and  labels  for  soils  map  layer  categories  10  and  20,  but  uses  (instead  erf  a 
tab)  as  the  character  separating  die  category  values  from  the  category  values  in  the  output. 

Example  output: 

10:Dumps,  mine,  Cc 
20:Kyle  clay,  KaA 

NOTES 

Any  ASOl  TAB  characters  which  may  be  in  the  label  are  replaced  by  spaces. 

The  output  from  r.cats  can  be  redirected  into  a  file,  or  piped  into  another  program. 
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SEE  ALSO 

UNIX  Manual  entries  for  awk  and  sort 

r.coin,  r. describe,  r.rast.what,  r support,  and  parser 

AUTHOR 

Michael  Shapiro,  u.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

r.clump  -  Recategorizes  data  in  a  raster  map  layer  by  grouping  cells  that  form  physically  discrete  areas 
into  unique  categories. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxlump 
r .clump  help 

rxlump  [-q]  input  =name  output  -name  [title="smng"] 

DESCRIPTION 

r.clump  finds  all  areas  of  contiguous  cell  category  values  in  the  input  raster  map  layer  name.  It 
assigns  a  unique  category  value  to  each  such  area  ("clump")  in  the  resulting  output  raster  map  layer 
name.  If  the  user  does  not  provide  input  and  output  map  layer  names  on  the  command  line,  the 
program  will  prompt  the  user  for  these  names,  using  the  standard  parser  interface  (see  manual  entry  for 
parser). 

Category  distinctions  in  the  input  raster  map  layer  are  preserved.  This  means  that  if  distinct  category 
values  are  adjacent,  they  will  NOT  be  clumped  together.  (The  user  can  run  rreclass  prior  to  r.clump 
to  recategorize  cells  and  reassign  cell  category  values.) 

Flag: 

Parameters: 
input  name 
output  =name 
title  =?  string" 

ALGORITHM 

r.clump  moves  a  2x2  matrix  over  the  input  raster  map  layer.  The  lower  right-hand  comer  erf  the  matrix 
is  grouped  with  the  cells  above  it,  or  to  the  left  of  it.  (Diagonal  cells  are  not  considered.) 

NOTES 

r.clump  works  properly  with  raster  map  layers  that  contain  only  "fat"  areas  (more  than  a  single  cell  in 
width).  Linear  elements  (lines  that  are  a  single  cell  wide)  may  or  may  not  be  clumped  together 
depending  on  the  direction  of  the  line  -  horizontal  and  vertical  lines  of  cells  are  considered  to  be 
contiguous,  but  diagonal  lines  of  cells  are  not  considered  to  be  contiguous  and  are  broken  up  into 
separate  clumps. 

A  random  color  table  and  other  support  files  are  generated  for  the  output  raster  map  layer. 

SEE  ALSO 

r.  average,  r.buffer,  r.combine,  r.grow,  r.infer,  r.mapcalc,  r.mfilter,  rjieighbors,  r.pciy,  r. reel  ass, 
r. support,  r. weight,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Amiy  Constniction  Engineering  Research  Laboratory 


Run  quietly,  without  printing  messages  on  program  progress  to  standard  output. 

Name  of  an  existing  raster  map  layer  being  used  for  input. 

Name  of  new  raster  map  layer  to  contain  program  output. 

Optional  title  for  output  raster  map  layer,  in  quotes.  If  the  user  fails  to  assign  a 
title  for  the  output  map  layer,  none  will  be  assigned  it. 


GRASS  4.0  (Summer  1991) 


U  S.  Annv  CERE 


237 


r.can 


GRASS  Reference  Manual 


rwotn 


NAME 

r.coin  -  Tabulates  the  mutual  occurrence  (coincidence)  of  categories  for  two  raster  map  layers. 

(GRASS  Rosier  Program) 

SYNOPSIS 

rxoin 
rxoin  help 

rxoin  [-qw]  mapl  name  map2  name  units  name 
DESCRIPTION 

r.coin  tabulates  the  mutual  occurrence  of  two  raster  map  layers’  categories  with  respect  to  one  another. 
'Ibis  analysis  program  respects  the  current  geographic  region  and  mask  settings. 

The  user  can  run  the  program  non-interactively  by  specifying  all  needed  flag  settings  and  parameter 
values  on  the  command  line,  in  the  form: 

rxoin  [-qw]  mupl  -  name  map2  =name  units  -name 

Flags: 

-q  Run  quietly,  and  supress  the  printing  of  program  status  messages  to  standard 

output. 

-w  Print  a  wide  report,  in  132  columns  (default:  80  columns) 

Parameters: 

mapl  name  Name  of  first  raster  map  layer. 

map2  =name  Name  of  second  raster  map  layer. 

unitsmwx  Units  of  measure  in  which  to  output  report  results. 

Options:  c,  p,  x,  y,  a,  h,  k,  m 

Alternately,  the  user  can  run  r.coin  interactively  by  simply  typing  rxoin  withrxit  command  line 
arguments;  in  this  case,  the  user  will  lx:  prompted  for  the  names  of  the  two  raster  map  layers  which  will 
be  the  subjects  of  the  coincidence  analysis,  r.coin  tlicn  talxilates  the  coincidence  of  category  values 
among  the  two  map  layers  ;uxl  prep;ires  the  basic  table  from  which  the  report  is  to  lx-  created.  Ihis 
tabulation  is  followed  by  an  indication  of  how  long  tlx  coincidence  table  will  !x\  If  the  table  is 
extremely  long,  the  user  may  decide  that  viewing  it  is  not  so  important  after  all.  aixl  may  cancel  the 
request  at  this  point.  Assuming  the  user  continues,  r.coin  then  allows  the  user  to  choose  one  of  eight 
units  of  measure  in  which  the  report  results  can  lx  given.  These  units  are: 

c  cells 

p  percent  cover  of  region 
x  percent  of  <lnap  name >  category  (column) 

y  percent  of  <map  namc> category  (row) 

a  acres 

h  hectares 

k  square  kilometers 

m  square  miles 

Note  that  three  of  these  options  give  results  as  percentile  values:  "p"  is  based  on  the  grand  total 
number  of  cells;  "x"  is  based  on  only  column  totals;  aixl  "y"  is  based  on  only  row  totals.  Ouh  oik-  unit 
of  measure  can  lx  selected  |xr  report  (xit|xit.  IV pe  in  just  one  of  the  letters  designating  a  unit  of 
measure  followed  bv  a  -]<KIUKN>.  Ihe  rejrort  will  lx  printed  to  the  screen  for  review.  Alter 
reviewing  the  re|x>rt  on  Ihe  screen,  the  user  is  given  several  options.  Ihe  report  may  lx  saved  to  a  file 
;ukl/or  sent  to  a  printer.  If  printed,  it  mav  lx  printed  with  either  <S()  or  132  columns,  linallv.  the  user 
is  given  the  option  to  renin  tlx  coincidence  lalxilation  using  a  different  unit  of  measurement 
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Below  is  a  sample  of  tabular  output  produced  by  rxoin.  Hoe,  map  output  is  stated  in  units  of  square 
miles.  The  report  tabulates  the  coincidence  of  the  Spearfish  sample  database’s  owner  and  rood  raster 
map  layers’  categories.  The  owner  categories  in  this  case  refer  to  whether  the  land  is  in  private  hands 
(category  1)  or  is  owned  by  the  U.S.  Forest  Service  (category  2).  Ihe  roads  map  layer  categories  refer 
to  various  types  of  roads  (with  the  exception  of  category  value  "0",  which  indicates  "no  data”;  i.e.. 
map  locations  at  which  no  roads  exist),  rxoin  does  not  report  category  labels.  The  user  should  run 
r. report  or  r.cats  to  obtain  this  information. 

The  body  of  the  report  is  arranged  in  panels.  The  map  layer  with  the  most  categories  is  arranged  along 
the  vertical  axis  of  the  table;  the  other,  along  the  horizontal  axis.  Each  panel  has  a  maximum  of  5 
categories  (9  if  printed)  across  the  top.  hr  addition,  the  last  two  columns  reflect  a  cross  total  of  each 
column  for  each  row.  All  of  the  categories  of  the  map  layer  arranged  along  the  vertical  axis  are 
included  in  each  panel.  Ihere  is  a  total  at  the  bottom  of  each  column  representing  die  sum  of  all  the 
rows  in  that  column  A  second  total  represents  the  sum  of  all  the  non  zero  category  rows.  A  cross 
total  (Table  Row  Total)  of  all  columas  for  each  row  appears  in  a  separate  panel. 

Note  how  the  following  information  may  be  obtained  from  the  sample  report. 

In  the  Spearfish  data  base,  in  area  not  owned  by  the  Forest  Service,  there  are  50.63  square  miles  of  land 
not  used  for  roads.  Roads  make  up  9.27  square  miles  of  land  in  this  area. 

Of  the  total  102.70  square  miles  in  Spearfish,  42.80  square  miles  is  owned  by  the  Forest  Service. 

In  total,  there  are  14.58  square  miles  of  roads. 

There  are  more  category  2  roads  outside  Forest  Service  land  (2.92  mi.  sq.)  than  there  are  inside  Forest 
land  boundaries  (0.72  mi.  sq.). 

Following  is  a  sample  report. 


COINCIDENCE  TABULATION  RETORT 

Location:  spearfish 

Mapset:  PERMANENT 

Date:  Wed  Jun  1  13:36:08 

Layer  1:  owner 

-  Ownership 

layer  2:  roads 

Mask:  none 

--  Roads 

Units:  square  miles 

Window: 

North:  4928000.00 

West:  590000.00 

South:  4914000.00 

East:  609000.00 
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NOTES 

It  is  not  a  good  idea  to  run  r.coin  on  a  map  layer  which  lias  a  monstrous  number  of  categories  (e  g., 
unreclassed  elevation).  1  fccau.se  r.coin  rejxrrts  information  for  each  and  every  category,  it  is  Ix-lter  to 
reclassify  those  categories  (using  reclass)  into  a  more  manageable  nuntlxr  prior  to  running  r.coin  on 
the  reclassed  raster  map  layer. 

r.coin  calculates  the  coincidence  ol  two  raster  map  lasers.  Although  r.coin  allows  the  user  to  renin 
the  report  using  different  units,  it  is  not  jxissible  to  simply  renin  the  report  with  different  map  layers. 
In  order  to  ch< * >se  ix'w  map  lasers,  it  is  necessarv  to  rerun  r.coin. 

SEE  ALSO 

r. region,  r.cats,  r.describe,  r.mask,  r. reclass,  r.repori,  r.stats 

AUTHORS 

Michael  (/Shea,  U.S.  Anny  (  onstmetion  l-jeriiuvring  Research  Ialxiratorv 
Michael  Shapiro.  U.S.  Anny  ('onstmetion  1  jigineering  Research  Ialxiratorv 
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NAME 

r. colors  -  Creates/Modifies  the  color  table  associated  with  a  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxoiors 
r .colors  help 

rxoiors  [-wq]  map  name  color  type 
DESCRIPTION 

r. colors  allows  the  user  to  create  and/or  modify  the  color  table  for  a  raster  map  layer.  The  map  layer 
(specified  on  the  command  line  by  map=name)  must  exist  in  the  user's  current  mapset  search  path. 
The  color  table  specified  by  color  =type  must  be  one  of  the  following: 


color  type  description 


aspect 

(aspect  oriented  grey  colors) 

grey 

(grey  scale) 

grey  eq 

(histogram-equalized  grey  scale) 

gy 

(green  through  yellow  to  red  colors) 

rainbow 

(rainbow  color  table) 

ramp 

(color  ramp) 

random 

(random  color  table) 

ryg 

(red  through  yellow  to  green  colors) 

wave 

(color  wave) 

rules 

(create  new  color  table  based  on  user-specified  rules) 

If  the  user  specifies  the  -w  flag,  the  current  color  table  file  for  the  input  map  will  not  be  overwritten. 
This  means  that  the  color  table  is  created  only  if  the  map  does  not  already  have  a  color  table.  If  this 
option  is  not  specified,  the  color  table  will  be  created  if  one  does  not  exist,  or  modified  if  it  does. 

If  the  user  sets  the  -q  flag,  r.colors  will  run  quietly,  without  printing  numerous  messages  on  its 
progress  to  standard  output. 

Color  table  types  aspect,  grey,  grey.eq  (histogram-equalized  grey  scale),  gyr  (green-yellow-red), 
rainbow,  ramp,  ryg  (red-yellow-green),  random,  and  wave  are  pre- defined  color  tables  that  r.colors 
knows  how  to  create  without  any  further  input. 

The  rules  color  table  type  will  cause  r.colors  to  read  color  table  specifications  from  standard  input 
(stdin)  and  will  build  the  color  table  accordingly. 

Using  color  table  type  rules,  there  are  three  ways  to  build  a  color  table:  by  color  list,  by  category 
values,  and  by  "percent"  values. 

Building  a  customized  color  table  by  color  list  is  the  simplest  of  the  three  rules  methods:  just  list  the 
colors  you  wish  to  apjrear  in  the  color  table  in  the  order  that  you  wish  them  to  appear.  Use  the 
standard  GRASS  color  names:  white,  black,  red,  green,  blue,  yellow,  magenta,  cyan,  aqua,  grey,  gray, 
orange,  brown,  purple,  violet,  and  indigo. 

l  or  example,  to  create  a  color  table  for  the  raster  map  layer  elevation  that  assigns  greens  to  low  map 
category  values,  bnavns  to  the  next  larger  map  category  values,  and  yellows  to  the  still  larger  map 
category  values,  one  would  type: 

r .colors  map  elevation  color  =rules 
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green 

brown 

yellow 

end 

To  build  a  color  table  by  category'  values’  indices,  the  user  should  determine  the  range  of  category 
values  in  the  raster  map  layer  with  which  the  color  table  will  be  used.  Specific  category  values  will 
then  be  associated  with  specific  colors.  Note  that  a  color  does  not  have  to  be  assigned  for  every  valid 
category  value  because  r.colors  will  interpolate  a  color  ramp  to  fill  in  where  color  specification  rules 
have  been  left  out.  The  format  of  such  a  specification  is  as  follows: 

category _value  color_name 
category_value  color_name 


category  .value  color.name 
end 

Each  category  value  must  be  valid  for  the  raster  map  layer,  category  values  must  be  in  ascending  order 
and  only  use  standard  GRASS  color  names  (see  above). 

Colors  can  also  be  specified  by  color  numbers  each  in  the  range  0-255.  The  format  of  a  category  value 
color  table  specification  using  color  numbers  instead  of  color  names  is  as  follows: 

category  .value  recLnumber  green.number  blue.number 
category  .value  recLnumber  green.number  blue.number 


category  .value  recLnumber  greerunumber  bjue.number 
end 

Specifying  a  color  table  by  "percent"  values  allows  one  to  treat  a  color  table  as  if  it  were  numbered 
from  0  to  100.  lhe  format  of  a  "percent"  value  color  table  specification  is  the  s;unc  as  fer  a  category 
value  color  specification,  except  that  the  category  v  alues  are  replaced  by  "percent"  values,  each  from 
0-100,  in  ascending  order.  Ihe  format  is  as  follows: 

percent_valuc%  color.name 
pcrcent_value%  color.name 

percent_valuc%  color.name 
end 

Using  "percent"  value  color  table  specification  rules,  colors  can  also  lx-  specified  bv  color  numbers  each 
in  the  range  0-255.  Ihc  format  of  a  percent  value  color  tahlc  specification  using  color  numlxrs  instead 
of  color  names  is  as  follows: 

|xrcent_  value%  red  nuinlxr  green.number  Huc.numlxT 
(x-rcent  \alue%  red.  nninlx-r  green. nuinlxr  Hue  numlxr 


ixrcent  valuc%  red_  nuinlxr  green. numlxr  blue  .number 
end 
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Note  that  you  can  also  nix  these  three  methods  of  color  table  specification;  for  example: 

0  Mack 

10%  yellow 

78  Mue 
mages  ta 
purple 
brown 

100%  0  255  230 
end 

EXAMPLES 

(1)  The  below  example  shows  how  you  can  specify  colors  for  a  three  category  map,  assigning  red  to 
category  1,  green  to  category  2,  and  blue  to  category  3.  Start  by  using  a  text  editor,  like  vi,  to  create 
the  following  rules  specification  file.  Save  it  with  the  name  rules.file. 

1  red 

2  green 

3  Mue 
end 

The  color  table  can  then  by  assigned  to  map  threecats  by  typing  the  following  command  at  the 
GRASS>  prompt: 

cat  rulcsillc  |  r -colors  map=threccats  color  =rules 

(2)  To  create  a  natural  looking  LUT  for  hue  map  layer  elevation,  use  the  following  rules  specification 
file.  It  will  assign  light  green  shades  to  the  lower  elevations  (first  20%  of  the  LUT),  and  then  darker 
greens  (next  15%,  and  next  20%)  and  light  browns  (next  20%)  for  middle  elevations,  and  darker  browns 
(next  15%)  for  higher  elevations,  and  finally  yellow  for  the  highest  peaks  (last  10%  of  LUT). 


0% 

0 

230 

0 

20% 

0 

160 

0 

35% 

50 

130 

0 

55% 

120 

100 

30 

75% 

120 

130 

40 

90% 

170 

160 

50 

100% 

255 

255 

100 

SEE  ALSO 

d.colormode,  d.colors,  d.colortable,  d. display,  eLlegend,  p.colors,  t support 
AUTHORS 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
David  Johnson,  DBA  Systems,  Jnc.  supplied  the  idea  to  create  this  program 
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NAME 

r.combine  -  Allows  category  values  from  several  raster  map  layers  to  be  combined. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxambtne 

r .combine  <inputfile 
DESCRIPTION 

r.combine  accepts  commands  that  are  similar  to  those  used  for  boolean  combinations  (AND,  OR,  NOT) 
in  order  to  overlay  user-selected  groups  of  categories  from  different  raster  map  layers.  Alter  the 
r.combine  program  is  started,  the  users  are  asked  if  they  want  the  graphic  output  to  go  to  ;t  color 
graphics  monitor.  If  a  color  graphics  monitor  is  not  used,  the  graphic  output  is  displayed  on  the 
terminal  screen.  Tltis  display  is,  of  course,  quite  rough.  It  consists  of  numerals  representing  the  various 
categories  that  result  from  the  r.combine  analysis.  The  user  will  see  a  [1]:  following  this  question. 
This  is  the  first  prompt,  ;md  indicates  that  r.combine  is  ready  to  receive  input  from  the  user. 

The  following  commands  perform  operations  in  r.combine: 


Command 

[Aliasl 

Followed  by 

Such  as 

NAME 

[name] 

name  for  raster 
map  output 

sandstone 

GROUP 

[group] 

fgrpl 

category  values 
and  a  raster  map 

1-40  (elevation .255) 

AND 

[and] 

{&{(&&] 

expression  describ¬ 
ing  a  raster  map 
and  categories 

(grp  4  (soils))  (grp  2  (owner)) 

OR 

[or] 

[iimi 

expression  describ¬ 
ing  a  raster  map 
and  categories 

(grp  4  (soils))  (grp  2  (owner)) 

NOT 

[not] 

n 

expression  describe 
ing  a  raster  map 
and  categories 

(grp  2  3  (roads)) 

OVER 

[over] 

[overlavl 

existing  raster  map 
and  color 

sandstone  yellow 

OOVER 

[cover] 

existing  raster  map 

sandstone 

r.combine  uses  the  same  colors  for  all  the  operating  commands.  This  is  the  r.combine  color  table: 
0  black  4  blue  8  grey  12  blue^rey 

1  red  5  purple  9  red/grey  13  purple^rey 

2  yellow  6  green  10  yellow/grey  14  green/grey 

3  orange  7  white  1 1  orange/grey  15  dark  grey 


'I he  user  may  enter  commands  cither  line-by-line  from  within  r.combine,  or  by  ty  ping  the  commands 
into  a  file  that  is  then  read  into  r.combine  using  the  UNIX  redirection  symbol  <.  Ihc  command  format 
is  the  same  for  the  two  methods.  The  line-by-line  method,  however,  does  not  allow  as  much  flexibility 
as  does  use  of  an  input  lilc.  If  a  line  containing  a  synttix  error  is  entered  on  the  r.combine  command 
line,  it  is  cleared;  the  line  must  then  Ire  re-entered  in  its  entirety.  Input  files  containing  mistakes, 
however,  can  easily  l>c  modified  (rather  than  recreated).  An  input  file  is  especially  advantageous  when 
a  more  complex  series  of  .statements  is  input  to  r.combine. 
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r. combine  uses  two  types  of  commands:  those  that  perform  operations,  and  those  that  have  some  other 
function. 

r. combine  can  probably  best  be  learned  by  following  examples,  so  pay  special  attention  to  those 
included  below'  with  the  operating  command  descriptions.  Notice  two  things  in  particular 

1)  All  parentheses  must  be  closed.  A  raster  map  layer  name  must  often  be  enclosed  within  parentheses; 
each  time  one  of  the  above  commands  is  used,  it  and  its  appropriate  companions  must  also  be  enclosed 
within  parentheses. 

2)  Certain  spaces  are  important.  Generally,  r. combine  requires  at  least  one  space  before  an  opening 
parenthesis  (except  when  it  is  the  first  character  in  an  expression),  r. combine  ignores  extra  spaces  and 
tab  characters. 

OPERA  1ING  COMMANDS 

Below  is  a  summary  of  the  syntax  of  the  operating  commands,  a  description  of  each  command,  and 
examples  using  the  Spearfish  sample  data  base. 

NAME 

(NAME  new_map_name  (Expression)) 

Allows  graphic  output  to  be  saved  in  the  raster  map  layer  new_map_name,  so  that  it  is  available 
for  additional  analysis  or  for  future  viewing.  The  results  of  performing  the  expression  in 
parentheses  is  then  placed  into  the  named  output  raster  map  layer  (here,  new  map  jiame ) .  Note 
that  this  means  that  r. combine  may  be  used  to  create  new  raster  map  layers  from  existing  ones. 
r. combine  automatically  creates  a  color  table  for  the  new  raster  map  layers;  however,  the  user 
should  nm  the  GRASS  program  rjupport  to  fill  in  category  assignments  and  history  information  if 
the  new  raster  map  layer  is  to  be  saved  for  future  use  in  the  mapset. 

Example: 

(NAME  sandstone  (GROUP  4  (geology))) 

The  above  command  will  result  in  the  creation  of  a  new  raster  map  layer  named  sandstone,  noting 
the  locations  of  cells  with  geology  category  value  4.  You  must  then  run  the  GRASS  program 
r. support  in  order  to  label  the  categories  present  in  the  new  raster  map  layer. 

Resultant  categories: 

0  -  black:  other  than  sandstone 
1  -  red:  sandstone 


GROUP 

(GROUP  category  .values  (existing  raster  map  layer)) 

Selects  out  categories  of  the  desired  values  from  the  existing  raster  map  layer  which  is  indicated  in 
parentheses  directly  after  the  category  grouping.  It  also  works  to  select  out  just  one  category  from 
the  map  layer.  Any  of  the  following  are  legal  category  groupings: 


2 

1-18 
1  2  5-7 


Be  ample: 

(GROUP  1-40  (elevation .255)) 

Depicts  ally  the  area  with  elevation  1187  meters  or  less  (i.e.,  elevation  map  layer  category  values 
1  through  40  only). 
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Resultant  categories: 

0  -  black:  elevation  >1187  m 
1  -  red  :  elevation  <=  1187  m 


Example: 

(NAME  lowjii  (GROUP  1^*0  238-255  (elevatioo.255))) 

Depicts  only  those  areas  with  elevations  of  either  1187  meters  or  less,  or  in  excess  of  1787  meters 
(elevation  categories  1  40,  and  238-255).  Tire  graphic  output  is  saved  in  the  new  raster  map  layer 
called  low. hi. 

Resultant  categories: 

0  -  black  :  elevation  >  1187  m  and  <1787  m 
1  -  red  :  elevation  <=  1187  m  ami  >--  1787  m 


AND 

(.AND  (Expression  A)  (Expression  B)) 

Combines  two  map  layers  and  creates  a  new  one;  when  BCTI'i  I  ol  the  category  values  associated 
with  the  same  given  cell  location  in  the  two  combined  map  layers  ~re  non- zero,  a  category  \alue  of 
1  is  assigned  to  that  cell  in  the  new  map  layer.  If,  however,  either  map  layer  assigns  a  category 
value  of  zero  to  the  same  given  cell  location,  the  category  value  associated  with  this  cell’s  location 
in  the  resultant  map  layer  also  becomes  zero. 

For  example, 


raster  map  1 


raster  map  2 


1 

~> 

0 

T 

1 

0 

0 

0 

0 

1 

0 

0 

and  -  -  >  1 

1 

0 

1 

0 

1 

0 

0 

0 

1 

1 

0 

1 

1 

0 

Example: 

(AND  (GROUP  4  7-9  (geology))  (GROUP  2  (owner))) 

Depicts  the  occurrences  of  categories  4,  7,  S,  and  9  from  the  map  layer  geology  whenever  they 
occur  on  U.S.  Direst  Service  property.  Results  are  displayed  to  the  terminal  screen. 

Resultant  categories: 

0  -  black  :  no  data  occurred  in  c.-»ie  or  the  other  of  tire  raster  map  layers 
1  -  red  :  the  AND  condition  is  met 

Note  that  if  neither  map  layer  contained  any  areas  of  "no  data."  the  resultant  raster  map  layer 
would  include  only  l’s. 

Example: 

(NAME  sand  (AND  (GROUP  4  7-9  (geology))  (GROUP  2  (owner)))) 

Same  as  alxrvc,  except  the  results  .ire  saved  in  the  map  layer  sand. 


OR 

(OF  (Expression  A)  (Expression  R)) 

Combines  two  map  layers  and  creates  a  new  one;  when  1 JTIIER  of  the  category  values  associated 
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with  the  same  given  cell  location  in  the  two  combined  map  layers  is  non-zero,  a  category  value  of 
1  is  assigned  to  that  cell  in  the  new  map  layer.  If,  however,  both  map  layers  assign  a  category 
value  of  zero  to  the  same  given  cell  location,  the  category  value  of  this  cell  in  the  resultant  map 
layer  also  becomes  zero.  Only  two  map  layers  may  be  combined  at  one  time.  For  example: 

raster  map  1  220 

2  1  0 

000  111  results 

or  -->  110 
raster  map  2101  110 

1  1  0 
1  1  0 

Example: 

(OR  (GROUP  4  7-9  (geology))  (GROUP  2  (owner))) 

Depicts  all  occurrences  of  categories  4,  7,  8,  and  9  from  the  map  layer  geology  as  well  as  showing 
all  the  land  which  is  U.S.  Forest  Service  property.  Results  are  displayed  to  the  terminal  screen. 
Resultant  categories: 

0  -  black:  this  area  has  neither  the  values  of  4,  7,  8,  or  9 
nor  is  it  on  U.S.  Forest  Service  property 
1  -  red  :  this  area  meets  one  or  the  other  of  die  conditions  noted  abcve 

Note  that  no  distinction  is  made  between  those  places  where  conditions  are  met  in  both  map  layers 
and  where  they  are  met  in  only  one.  See  the  r.combine  command  OVER  if  it  is  necessary  to  make 
that  distinction. 


NOT  (NOT  (Expression)) 

Negates  Expression  in  order  to  define  a  new  map  layer  which  contains  the  opposite  of  what  is 
defined  by  Expression.  The  new  raster  map  layer  will  contain  category  values  of  either  0  or  1.  0 
values  would  indicate  that  the  NOT  conditions  were  not  met.  Cell  values  of  1  would  indicate  that 
die  NOT  conditions  were  met.  In  order  to  specify  the  map  layer  in  which  to  save  the  output  from 
NOT,  use  the  r.combine  command  NAME. 

Example: 

(NAME  rds  (NOT  (GROUP  0  (roads)))) 

Areas  containing  category  zero  in  the  existing  map  layer  roans  indicate  those  locations  within  the 
data  base  where  roads  do  not  exist.  Negating  that  expression  leaves  us  with  all  other  areas  -  i.e., 
those  locations  at  which  roads  do  exist.  Here,  the  graphic  output  is  saved  in  the  raster  map  layer 
named  rds. 

Resultant  categories: 

0  -  black:  no  roads 
1  -  red  :  roads 

The  same  results  could  have  been  obtained  with:  (NAME  rds  (GROUP  1-5  (roads))).  NOT  is 
most  useful  in  those  cases  where  it  is  simpler  to  define  something  on  the  basis  of  what  it  is  not 
than  on  the  basis  of  what  it  is. 


OVER 

(OVER  color  (Expression))  or  (OVER  existing_rastermap  color  (Expression)) 

Performs  a  transparent  overlay  operation.  This  means  that  when  a  map  layer  that  depicts  some  feature 
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in  blue  is  overlaid  with  one  that  depicts  a  feature  in  yellow,  the  res  id  tire’  raster  map  layer  will  show 
areas  of  overlap  in  green;  areas  in  the  two  raster  map  layer  that  do  not  overlap  other  areas  maintain 
their  original  colors  (i.e.,  yellow’  or  blue). 

OVER  may  be  nui  with  or  without  an  existing  map  layer  name.  If  the  user  does  not  specify  an  existing 
raster  map  layer  name,  OVER  applies  the  color  specified  to  the  expression  in  parentheses  and  displays 
the  results.  If  an  existing  raster  map  layer  name  is  specified,  OVER  applies  the  color  to  the  expression 
(just  as  before)  and  then  overlays  the  results  on  top  of  the  existing  raster  map  layer.  In  order  to  make 
sense  of  the  colors  which  result,  use  only  those  existing  map  layers  created  using  OVER. 

OVER  allows  the  user  to  specify  just  fair  colors: 
color  value 

red  1 
yellow  2 
blue  4 
grey  8 

'Ihese  four  colors  arc  then  combined  to  firm  other  colors.  The  number  of  progressive  overlays  allowed 
is  limited  to  four  (one  for  each  of  the  basic  colors  above).  The  actual  number  of  colors  on  the  resultant 
raster  map  layer,  however,  varies  depending  on  the  distribution  of  the  features  and  chi  the  interaction  of 
the  features  from  the  different  map  layers  which  are  overlaid.  When  two  or  more  of  these  colors  are 
ov  erlaid,  new  colors  are  created.  The  numerical  values  associated  with  the  colors  above  are  significant, 
in  that  the  values  of  any  additional  colors  created  reflect  the  sum  of  two  cm-  more  of  the  four  above. 
'Iliese  overlaid  color  values  appear  on  the  resultant  overlay  as  cell  (category)  values.  Ihe  user  should 
know  what  these  values  represent  in  order  to  know’  what  category  information  is  to  be  associated  with 
the  new  map  layer  (entered  using  the  GRASS  r support  command),  and  to  know  the  significance  of 
this  and  subsequent  analyses  involving  the  new  map  layer. 


Any  of  these  colors  and  category  values  may  result  from  OVER.  Note  that  this  is  the  same  as  the 
r. combine  color  table  listed  above. 


0  black 

4  blue 

8  grey 

12  Mue^rey 

1  red 

5  purple 

9  red/grey 

13  purple/grey 

2  yellow 

6  green 

10  yellow/grey 

14  green/grey 

3  orange 

7  white 

11  orange^grey 

15  dark  grey 

Ihe  syntax 

for  OVER  makes  no  provision  for  a  new  ras 

r. combine  operator  NAME  to  specify  a  new  raster  map  layer  name  in  which  to  sav  e  the  graphic  output 
generated  by  OVER.  If  the  user  runs  OVER  without  specifying  an  output  raster  map  layer  name, 
aitput  is  displayed  to  the  terminal.  However,  this  output  is  available  for  ftiture  use  only  if  it  is  saved 
using  the  NAME  command. 


Example: 

(NAME  park.or.priv  (OVER  red  (GROUP  1  (owner)))) 

Ihe  new  raster  map  layer  park.or.priv  displays  private  land  (i.e.,  category  1  of  the  raster  map  layer 
owner)  in  red,  and  displays  U.S.  Forest  Service  land  (i.e.,  "no  data"  areas  within  the  owner  map  layer) 
as  black. 

Resultant  categories: 

0  -  black  :  park 
1  -  red  :  private  land 


ixample: 

(NAME  roads.or.not  (OVER  park.or.priv  yellow  (GROUP  0  (roads)))) 
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Category  0  in  the  map  layer  roads  is  overlaid  in  yellow  on  top  of  the  park.or.priv  map  layer  created 
above.  The  output  is  placed  in  a  new  map  layer  named  roads.orjvot. 

Resultant  categories  in  roads.orjiot  are: 

0  -  Mack  :  park;  road 

1  -  red  :  private;  road 

2  -  yellow  :  park;  no  road 

3  -  orange  :  private;  no  road 

Example: 

(NAME  low  .dev  (OVER  park.or.priv  bloc  (GROUP  1-19  (devstion.255)))) 

The  elevation  categories  of  1123  meters  or  less  from  the  map  layer  elevation.255  are  assigned  the 
color  blue  and  then  overlaid  on  park.or.priv  (generated  in  the  previous  example). 

Resultant  categories  in  the  new  map  layer  low.elev  are: 

0- black  :  park;  >1123  m 
1  -  red  :  private;  >1123m 

4  -  Hue  :  park;  <=  1123  m 

5  -  purple  :  private;  <=  1123m 

Note  how  category  5  is  the  sum  of  red  (1)  +  Hue  (4)  (i.e.,  the  intersection  of  areas  containing  low 
elevations  and  private  lands  with  roads). 


COVER 

(COVER  existing_map  (Expression)) 

Performs  an  opaque  overlay  operation.  This  means  that  where  the  top  map  layer  contains  "holes"  (cell 
category  values  of  0),  the  bottom  map  layer  will  show  through.  Where  the  top  map  layer  contains 
information  on  a  feature,  it  will  cover  (substitute  its  category  value  for)  whatever  is  below  it.  The  top 
map  layer  is  that  which  is  defined  by  Expression.  The  bottom  map  layer  is  existingjnap ;  this  map 
layer  must  already  exist. 

The  user  does  not  specify  colors  with  COVER.  COVER  uses  the  default  color  table  that  is  listed  above 
with  OVER  Colors  are  assigned  starting  with  the  lower  map  layer.  The  category  values  are  assigned 
die  color  from  the  table  that  corresponds  with  that  value.  For  example,  1  would  be  red;  2,  yellow;  3, 
orange,  etc.  Moving  to  the  upper  map  layer  COVER  starts  wherever  it  left  off  after  die  lower  one.  If 
the  highest  value  of  the  lower  map  layer  was  5,  then  all  non-zero  (i.e.,  places  where  a  feature  exists) 
cells  of  the  upper  map  layer  would  be  assigned  the  value  of  6  (green).  Note  that  if,  in  this  case,  the 
upper  map  layer  did  not  have  any  cells  of  value  zero,  then  the  entire  resulting  new  map  layer  would  be 
green.  The  upper  map  layer  would  have  been  assigned  the  value  6  and  would  have  completely  covered 
that  which  was  below  it. 

This  is  what  happens: 


Expression  1110 

(top  raster  map)  1100 

0  0  0  0 

--> 

olcknap  2  5  0  0 

(bottom  raster  map)  0  5  2  0 

5  5  2  2 


6  6  6  0 
6  6  2  0 
5  5  2  2 


resul  t 


As  many  map  layers  may  be  overlaid  as  is  desired.  However,  there  is  a  practical  limit  on  the  number 
of  map  layers  that  can  be  used  while  still  generating  sensiHe  output.  That  number  depends  on  the 
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features  involved  in  each  map  layer,  and  how  many  cells  within  the  upper  (overlying)  map  layers 
contain  category  values  of  zero  (holes  through  which  underlying  data  can  be  seen). 

COVER  has  no  provision  for  saving  graphic  output.  Use  the  r.combine  command  NAME  to  save 
output  in  a  raster  map  layer. 

Example: 

(NAME  lo.elev  (COVER  owner  (CROUP  1-19  (elevation .255)))) 

The  categories  that  indicate  elevation  of  1123  meters  or  less  are  placed  on  top  of  the  existing  map  layer 
owner.  Output  is  saved  in  lo.elev. 

Resultant  categories: 

1  -  red  :  private  ownership;  elev  >1123  m 

2  -  yellow  :  park  property;  elev  >1123  m 

3  -  orange  :  park  or  private;  elev  O  1123  in 

Example: 

(NAME  sand.lo  (COVER  lo.elev  (GROUP  4  (geology)))) 

Category  4  of  geology  (sandstone)  is  placed  on  top  of  lo.elev,  the  raster  map  layer 
created  in  the  previous  example.  The  output  is  saved  in  sand.lo. 

Resultant  categories: 

1  -  red  :  private  (Ownership;  elev  >1123  m;  no  sandstone 

2  -  yellow  :  p;irk  property  ;  elev  >1123  m  ;  no  sandstone 

3  -  orange  :  park  or  private;  elev  <=  1 123  m;  no  sandstone 

4  -  blue  :  park  or  private;  any  elev;  sandstone 

ADDITIONAL  COMMANDS 

r.combine  also  contains  a  number  of  commands  which  are  not  used  for  operations, 
but  serve  a  variety  of  other  functions.  Additional  commands: 


Command 

Alias 

Followed  Bv 

QUIT 

CA'l'S 

quit  q  exit  bye 
categories  cats 

existing  raster  map 

EXP 

exp  expr 

number  of  an  expression 

t 

< 

WINDOW 

window 

shell  command  eg.,  vi  comb.l 
existing  input  hie 
existing  raster  map  layer 

HISTORY 

HEIT* 

history  hist 
help 

combine  command  for  which  help  is  needed 

ERASE 

erase 

QUIT 

Allows  the  user  to  exit  from  r.combine  while  remainirg  within  the  GRASS  session. 
CATS  (’ATS  raster  map 

Gives  user  an  on-line  listing  of  categories  and  labels  for  the  map  layer  specified.  For 
example: 

[1]:CATS  owner 

1X1*  EXP  expression  number 

During  an  r.combine  session,  each  completed  expression  and  command  is  assigned  a 
numlxr.  This  number  may  lx-  used  to  reference  the  expression  to  which  it  is  assigned; 
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this  means  that  the  user  can  substitute  the  number  of  the  expression  for  the  expression 
itself. 

fGr  example: 

[4] :  (GROUP  5  (geology)) 

[5] : (NAME  limestone  (EXP  4)) 

Use  the  UNIX  history  mechanism  (explained  below)  to  determine  the  specific  numbers 
associated  with  particular  expressions  in  your  current  r. combine  session. 

!  .'shell  command 

Allows  user  to  temporarily  suspend  r. combine  and  go  run  another  command,  as  in  the 
two  examples  belexv: 

!vi  input 
!g  .list  type=rast 

Unless  otherwise  specified  by  the  user,  when  a  file  is  created  using  a  system  editor 
(like  vi)  from  within  r. combine,  this  file  will  be  placed  in  the  user’s  mapset  under  the 
COMBINE  directory.  After  the  command  is  completed,  control  returns  to  r.combine. 

<  <  input  filename 

Takes  input  from  the  specified  filename  containing  r.combine  commands.  The  user, 
of  course,  must  previously  have  entered  the  commands  into  this  named  input  file.  If 
no  pathname  is  given,  the  input  file  is  assumed  to  be  in  the  user’s  mapset  under  the 
COMBINE  directory.  For  example,  the  user  would  perform  the  following  steps  to 
redirect  input  from  the  file  comb. in  into  the  r.combine  program  (while  within 
r.combine): 

first,  the  user  would  create  the  file:  !▼!  combia 

Second,  the  user  would  direct  r. combine  to  take  its  input  from  the  file:  <combJa 
WINDOW  WINDOW  raster _map 

Gves  on-line  geographic  region  (window)  information  about  the  raster  map  layer 
specified. 

HISTORY 

Provides  a  listing  of  all  previously  completed  expressions  used  within  the  current 
rxombine  session,  and  the  numbers  associated  with  the  execution  of  these  commands. 

HELP  HELP  command 

An  on-line  help  facility  for  r.combine  commands  only.  Type  in  the  name  of  the 
r.combine  command  for  which  help  is  needed,  to  see  the  entry  for  that  command. 

ERASE 

Will  cause  the  color  graphics  monitor  to  clear. 
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NOTES 

In  all  of  the  above  examples,  only  a  single  line  erf  input  was  provided  to  r.combine.  However,  since 
r.combine  conveniently  ignores  extra  spaces  and  tabs,  it  is  possible  to  type  input  to  r.combine  in  the 
manner  outlined  below  .  Users  may  find  this  to  more  clearly  exhibit  the  relationships  involved  and 
parentheses  needed.  This  can  be  typed  as  shown  belcw  either  directly  at  the  r.combine  command  line, 
or  redirected  into  r.combine  from  an  already  existing  file. 

Be  ample: 

(NAME  good  .pi  ace 
(AND 

(OR 

(GROUP  1  2  5  (geology)) 

(GROUP  1-5  (elevation .255)) 

) 

(NOT 

(GROUP  1-4  (landuse)) 

) 

) 

) 

Such  involved  input  to  r. combine  might  conveniently  be  typed  into  an  input  file,  and  then  input  to 
r.combine  using  the  UNIX  redirection  mechanism  < . 

SEE  ALSO 

GRASS  Tutorial:  r.combine 

r. infer,  rjnapcalc,  r. weight 

AUTHORS 

L.  Van  Warren,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Michael  Shapiro,  U.S.  Army  Constniction  Engineering  Research  laboratory 
James  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory' 
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NAME 

r. compress  -  Compresses  and  decompresses  raster  files. 

(GRASS  Raster  Program) 

SYNOPSIS 

r-com  press 
rxom press  help 

r .com press  [-a]  map  =name\  /tame,...) 

DESCRIPTION 

The  GRASS  program  r, compress  can  be  used  to  compress  and  decompress  raster  map  lav<  .a. 

During  compression,  this  program  reformats  raster  files  using  a  run- length- encoding  (RLE)  algorithm. 
Raster  map  layers  which  contain  very  little  information  (such  as  boundary,  geology,  soils  and  land  use 
maps)  can  be  greatly  reduced  in  size.  Some  raster  map  layers  are  shrunk  to  roughly  1%  of  their 
original  sizes.  Raster  map  layers  containing  complex  images  such  as  elevation  and  photo  or  satellite 
images  may  increase  slightly  in  size.  GRASS  uses  a  new  compressed  format,  and  all  new  raster  files 
are  now  automatically  stored  in  compressed  form  (see  FORMATS  below).  GRASS  programs  can  read 
both  compressed  and  regular  (uncompressed)  file  formats.  This  allows  the  use  of  whichever  raster  data 
format  consumes  less  space. 

As  an  example,  the  Spearfish  data  base  raster  map  layer  owner  was  originally  a  size  of  26600  bytes. 
After  it  was  compressed,  the  raster  file  became  only  1249  bytes  (25351  bytes  smaller). 

Raster  files  may  be  decompressed  to  return  them  to  their  original  formal,  using  the  -u  option  rtf 
r.compress.  If  r.compress  is  asked  to  compress  a  raster  file  which  is  already  compressed  (or  to 
decompress  an  already  decompressed  file),  it  simply  informs  the  user  of  this  and  asks  the  user  if  he 
wishes  to  perform  the  reverse  operation. 

PROGRAM  OPTIONS 

r.compress  can  be  run  either  non-interactively  or  interactively.  In  non-interactive  use,  the  user  must 
specify  the  name(s)  of  the  raster  map  layer(s)  to  be  compressed  (or  decompressed)  on  the  command 
line,  using  the  fonn  map=name[/iame ,...]  (where  each  name  is  the  name  of  a  raster  map  layer  to  be 
compressed  or  decompressed).  To  decompress  a  map,  the  user  must  include  the  -u  option  on  the 
command  line.  If  the  - u  option  is  not  included  on  the  command  line,  r.compress  will  attempt  to 
compress  the  named  map  layer(s). 

If  the  user  simply  types  r.compress  without  specifying  any  map  layer  name(s)  on  the  command  line, 
r.compress  will  prompt  the  user  for  the  names  of  the  map  layers  to  be  compressed/decompressed,  and 
ask  whether  these  maps  are  to  be  compressed  or  decompressed.  This  program  interface  is  the  standard 
GRASS  parser  i  tit  erf  .ace  described  in  the  manual  entry  for  parser. 

Flags: 

-u  If  set,  r. compress  converts  a  compressed  map  to  its  uncompressed 

format.  If  not  set,  r.compress  will  attempt  to  compress  the  named  map 

layer(s). 

Parameters: 

map  =name[name,....}  The  name(s)  of  raster  map  layers)  to  be  compressed  or  decompressed. 

FORMATS 

Conceptually,  a  raster  data  file  consists  of  rows  of  cells,  with  each  row  containing  die  same  number  of 
cells.  A  cell  consists  erf  one  or  more  bytes.  The  number  of  bytes  per  cell  depends  on  the  category 
values  stored  in  the  cell.  Category  values  in  the  range  0-255  require  1  byte  per  cell,  while  category 
values  in  the  range  256-65535  require  2  bytes,  and  category  values  in  the  range  above  65535  require  3 
(or  more)  bytes  per  cell. 
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Ihe  decompressed  raster  file  format  matches  tile  conceptual  format,  for  example,  a  raster  file  with 
1-byte  cells  that  is  1CK)  rows  with  200  cells  per  row,  consists  of  20,(XXJ  bytes.  Running  the  UNIX 
command  Is  l  on  this  file  will  show  a  size  of  2(),(XK).  If  the  cells  were  2-lnte  cells,  the  file  would 
require  40,000  bytes.  Ihe  map  layer  category  values  start  with  the  upper  left  comer  cell  followed  by 
the  other  cells  along  the  northern  boundary.  Ihe  byte  following  the  last  byte  of  that  first  row  is  the  first 
cell  of  the  second  row  of  category  values  (moving  from  left  to  right).  Ihere  are  no  end-of-row  markers 
or  other  syncing  codes  in  the  raster  file.  A  cell  header  file  ( cellhd)  is  used  to  define  how  this  string  of 
bytes  is  broken  up  into  rows  of  category  values. 

The  compressed  format  is  not  so  simple,  but  is  quite  elegant  in  its  design.  It  not  only  requires  less 
disk  space  to  store  the  raster  data,  but  often  can  result  in  faster  execution  of  graphic  and  analysis 
programs  since  there  is  less  disk  I/O.  Ihere  are  two  compressed  formats:  the  pre-version  3.0  format 
(which  GRASS  programs  can  read  but  no  longer  produce),  and  the  version  3.0  format  (which  is 
automatically  used  when  new  raster  map  layers  are  created). 

PRE-3.0  FORMAT: 

first  3  bytes  (chars)  -  'Ihese  are  a  special  code  that  identifies  the  raster  data  as  compressed. 

Address  array  (long)  -  array  (size  of  the  number  of  row  s  +  1)  of  addresses  pointing  to  the  internal  start 
of  each  row.  Because  each  row  may  be  a  different  size,  this  array  is  necessary  to  provide  a  mapping  of 
the  data. 

Row  by  rowy  beginning  at  the  northern  edge  of  the  data,  a  series  of  byte  groups  describes  the  data. 
The  number  of  bytes  in  each  group  is  the  number  of  bytes  per  cell  plus  one.  'Ihe  first  byte  of  each 
grextp  gives  a  count  (up  to  255)  of  the  munlxT  of  cells  that  contain  the  category  values  given  by  the 
remaining  bytes  of  the  group. 

POST- 3.0  FORMAT: 

Ihe  3  by  te  code  is  not  used.  Instead,  a  field  in  the  cell  header  is  used  to  indicate  compressed  format. 
Ihe  address  tirray  is  the  same. 

Ihe  RIJK  format  is  the  same  as  the  pic  3.0  Rl.l  .  except  that  each  row  of  data  is  preceded  by  a  single 
byte  containing  the  numlxr  of  bytes  [v:  cell  for  the  row,  ;uul  il  nm  length-encoding  the  row  would  not 
require  less  space  than  non  mil  length  cncmling,  then  the  row  is  not  enoxled. 

Ihese  improvements  give  Ix-tter  compa  ssion  than  the  pre  3.0  lonn.it  in  of  the  raster  data  lay  ers. 
Ihe  kinds  ot  raster  data  layers  which  get  bigger  are  those  in  which  each  ua\  would  lx-  huger  if 
compressed  (e  g.,  imagery  Ixind  files).  But  even  in  litis  case  the  raster  ilata  layer  would  only  lx*  huger 
bv  the  size  of  the  address  array  and  the  single  byte  preceding  each  row . 

SEE  ALSO 

r. support,  and  parser 

AUTHORS 

James  Westered t.  U.S.  Army  (  nnstnution  Tnginecring  Research  Ialxxaiory 
Michael  Shapiro.  U.S.  Anny  C  onstniclion  lug  meeting  Kesc.uch  Inlxiraiory 
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NAME 

r.cost  -  Outputs  a  raster  map  layer  showing  the  cumulative  cost  of  moving  between  different 
geographic  locations  on  an  input  raster  map  layer  whose  cell  category  values  represent  cost. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.cost 
rxost  help 

rxost  input  name  output  =name  j  coordinate  =^r,y[,x,j-,...]] 

DESCRIPTION 

r.cost  determines  the  cumulative  cost  of  moving  to  each  cell  on  a  cost  surface  (the  input  raster  map 
layer)  from  other  user-specified  cell(s)  whose  locations  are  specified  by  their  geographic  coordinate^). 
Each  cell  in  the  original  cost  surface  map  will  contain  a  category  value  which  represents  the  cost  of 
traversing  that  cell,  r.cost  will  produce  an  output  raster  map  layer  in  which  each  cell  contains  the 
lowest  total  cost  of  traversing  the  space  between  each  cell  and  the  user-specified  points.  (Diagonal 
costs  are  multiplied  by  a  factor  that  depends  on  the  dimensions  of  the  cell.)  This  program  uses  the 
current  geographic  region  settings. 

OPTIONS 

r.cost  can  be  mn  either  non- interactively  or  interactively.  The  program  will  be  run  non-interactively  if 
the  user  specifies  the  names  of  raster  map  layers  and  any  desired  options  on  the  command  line,  using 
the  form: 

rxost  input  -name  output  name  [coordinate  =x,y[f,y,-\\ 

where  the  input  name  is  the  name  of  a  raster  map  layer  representing  the  cost  surface  map,  the  output 
name  is  the  name  of  a  raster  map  layer  of  cumulative  cost,  and  each  x,y  coordinate  pair  gives  the 
geographic  location  of  a  point  from  which  the  transportation  cost  should  be  figured. 

Alternately,  the  user  can  simply  type  r.cost  on  the  command  line,  without  program  arguments.  In  this 
case,  the  user  will  lx-  prompted  for  parameter  values  using  the  standard  GRASS  parser  interface 
described  in  the  manual  entry  for  parser. 

r.cost  can  lx:  nui  with  two  different  methods  of  identifying  the  starting  point(s).  One  or  more  points 
(geographic  coordinate  pairs)  can  be  provided  on  the  command  line.  In  lieu  of  command  line 
«x>rdi nates,  a  map  of  starling  point  (eg.,  start _pt_map)  may  already  exist.  Primarily  filled  with  zeros, 
this  map  contains  non-zero  values  at  the  starting  cell(s).  To  submit  the  start_pt_map,  set 
cn\ipM=start_pt_map.  Beware:  doing  this  will  overwrite  start _pt_map  with  the  results  of  the 
calculations.  If  start _j)t_map  does  exist  and  points  are  also  given  on  the  command  line,  the 
start  pt  map  is  ignored  and  the  coordinates  given  on  the  command  line  are  used  instead. 

Parameters: 

input  =name  Name  of  input  raster  map  layer  whose  category  values  represent  surface  cost. 

output  name  Name  of  raster  map  layer  to  contain  output.  Also  can  be  used  as  the  map  layer  of 

the  input  startiig  points.  If  so  used,  the  input  starting  point  map  will  be 
overwritten  by  the  ixitput. 

coordinate  ~x,y\  jc,y,x,y,  ...] 

Each  x.y  coordinate  pair  gives  the  easting  and  northing  (respectively)  geographic 
ciK>rdinatcs  of  a  starting  point  from  which  to  figure  cumulative  transportation 
costs  fix  each  cell. 

As  mam  |xxnts  as  desired  can  be  entered  by  the  user. 
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EXAMPLE 

Consider  the  following  example: 
Input : 

Cost  Surface 


n 

2 

.  1 

.  1 

5 

5 

.  5  . 

.  2 

2 

.  8 

.  8 

5 

2 

.  1  . 

.  7 

1 

.  1 

.  8 

2 

2 

2 

.  8 

7 

.  8 

.  8 

7 

.  5 

.  5  . 

.  8 

8 

.  1 

.  1 

5 

1 

1  9  . 

1 

.  8 

1 

.  1 

5 

1 - 

.  3 

1  •  • 

.  9  . 

Qitput : 

Qmilat  ive  Cost  Surface 


22 . 

20. 

18. 

17. 

19. 

17. 

16. 

oo 

21 . 

26. 

22 

16. 

12. 

11 . 

.  26. 

19. 

18. 

19. 

11  . 

10. 

11 . 

.  28. 

20. 

18. 

17. 

13. 

8  . 

10. 

.  22. 

18. 

10. 

9  . 

8  . 

0  . 

12. 

.  19. 

11  . 

10. 

11  . 

10. 

6  . 

16. 

The  user-provided  ending  location  in  the  above  example  is  the  boxed  3  in  the  left-hand  map.  The  costs 
in  the  txitput  map  represent  the  total  cost  of  mov  ing  from  each  box  ("cell")  to  one  or  more  (here,  only 
one)  starting  location^).  This  output  map  can  be  viewed,  for  example,  as  ;tn  elevation  model  in  which 
the  starting  Kxation(s)  is/are  the  lowest  point(s).  Outputs  from  r.cost  can  lx:  used  as  inputs  to  r.drain, 
in  order  to  trace  the  least-cost  pith  given  in  this  model  between  tun  given  cell  and  the  r.cost  starting 
location(s).  Ilic  two  programs,  when  used  togetlier,  generate  least-cost  piths  or  corridors  Ixtween  am 
two  map  locations  (cells). 

NOTES 

If  you  submit  the  starting  point  map  on  the  command  line  by  specifying: 

output  start  pt  map 

the  starting  point  map  will  lx  overwritten  by  the  c;tloulated  output.  It  is  wise  to  copy  or  rename  (e.g.. 
using  g.copy  or  g. rename)  the  map  of  startiig  points  to  another  name  lx*  I  ore  submitting  it  to  r.cost: 
otherwise,  its  contents  will  be  overwritten. 

Sometimes,  when  (lie  differences  among  cell  category  values  in  the  r.cost  cumulative  cost  surtace 
output  are  small,  this  cumulative  cost  output  cannot  accurately  lx  used  as  input  to  r.drain  (r.drain  will 
output  bad  results).  Ibis  problem  can  lx  circumvented  by  making  the  differences  Ix-lween  cell  categon 
values  in  the  cumulative  cost  output  bigger.  It  is  recommended  that,  if  tlx’  output  from  r.cost  is  to  lx 
used  as  input  to  r.drain.  tlx  user  multiply  the  injxil  cost  surface  map  to  r.cost  by  tlx-  value  of  the 
map's  cell  resolution,  before  running  r.cost.  Ibis  can  lx  done  using  r.ntapcalc  or  otlxr  programs. 
Ihc  map  resolution  can  lx  found  using  g. region. 

SEE  ALSO 

g.copy,  g.region,  g.rename,  r.drain,  r.in.ascii,  r.mapcalc,  r. out. ascii,  and  parser 

AUTHOR 

Antony  Awaida.  Intelligent  linginccring  Systems  laboratory.  Mil 
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NAME 

r.covar  -  Outputs  a  covariance/correlation  matrix  for  user-specified  raster  map  layers). 

( GRASS  Raster  Program) 

SYNOPSIS 

r.covar 
r.covar  help 

r.covar  [-mrqj  map  =name[ /tame,...] 

DESCRIPTION 

r.covar  outputs  a  covariance/correlation  matrix  for  user-specified  raster  map  layers).  The  output  can 
be  printed,  or  (if  run  non-interactively)  saved  by  redirecting  output  into  a  file. 

The  output  is  an  N  x  N  symmetric  covariance  (correlation)  matrix,  where  N  is  the  number  of  raster  map 
layers  specified  on  the  command  line.  For  example, 

rxuvar  map=l^tr.l)aytr2)aycrJ 

would  produce  a  3x3  matrix  (values  are  example  only): 

462.876649  480.411218  281.758307 

480.411218  513.015646  278.914813 

281.758307  278.914813  336326645 

OPTIONS 

The  program  will  be  run  non-interactively,  if  the  user  specifies  the  names  of  raster  map  layers  and  any 
desired  options  on  the  command  line,  using  die  form 

rxovar  [-mrq]  map=name[/uune,..] 

where  each  name  specifies  the  name  of  a  raster  map  layer  to  be  used  in  calculating  die  correlations, 
and  the  (optional)  flags  -m,  -r,  and  -q  have  meanings  given  belcKv.  If  these  flags  are  not  specified  on 
the  command  line,  their  answers  default  to  "no.” 

Flags: 

-m 
-r 

-q 

Parameters: 

map  name[  /iame ,...]  Existing  raster  map  layers)  to  be  included  in  the  covariance/correlation 

matrix  calculations. 

Alternately,  the  user  can  simply  type  rxovar  on  the  corranand  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  flag  settings  and  parameter  values  using  the  standard  GRASS 
parser  interface  described  in  the  manual  entry  for  parser. 

PRINCIPLE  COMPONENTS 

'Ibis  module  can  be  used  as  the  first  step  of  a  principle  components  transformation.  The  covariance 
matrix  would  be  input  into  a  system  which  determines  eigen  values  and  eigen  vectors.  An  NxN 
covariance  matrix  would  result  in  N  real  eigen  values  and  N  eigen  vectors  (each  composed  of  N  real 
rxunbers).  In  the  above  example,  the  eigen  values  and  corresponding  eigen  vectors  for  the  covariance 
matrix  are: 


Include  zero  values  in  the  correlation  calculations,  due  to  die  mask. 
Print  out  the  correlation  matrix. 

Run  quietly  (without  comments  on  program  progress;. 
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component 

1 

eigen  value 

11 59.  '45202 

< 

0.69 1002 

eigen  vector 
0.72052 8 

0.480511 

> 

*"> 

5.070541 

< 

0.71 1939 

-0.635820 

-0.070394 

> 

3 

146.503197 

< 

0226584 

0347470 

-0346873 

> 

The  component  corres|x  Hiding  to  each  vector  can  lx;  prixluced  using  r.mapcalc  as  follow  s: 

r.mapcalc  ’pc.l  =  0.691002*layer.l  +  0.720528* layer .2  +  0.480511* layer 3’ 
rjnapcair  'pc .2  =  0.7 1 1939*  layer. 1  —  0.635820* layers  —0.070394*  layer  3’ 
r.mapcalc  ’pc3  -  0.226584*  layer. 1  +  0347470* layers  —0.846873*  lay  er3’ 

Note  that  based  on  the  relative  sixes  of  the  eigen  values,  pc.l  will  contain  about  88%  of  the  variance  in 
the  data  set,  pc. 2  will  contain  alx>ut  1%  of  the  variance  in  the  data  set,  and  pc. 3  will  contain  alxxit 
11%  of  the  variance  in  the  data  set. 

Also,  note  that  the  range  of  v;tlties  produced  in  pc.l,  pc.2.  and  pc.3  will  not  (in  general )  lx-  the  same 
as  those  for  layer.  I,  layer. 2,  and  layer. 3.  It  may  lx-  necessary  to  rescale  pc.l,  pc.2  and  pc.3  to  the 
desired  range  (eg.,  0  255).  Ibis  c;ui  lx-  done  with  r. rescale. 

NOTES 

If  your  system  has  a  FORTRAN  compiler,  then  the  program  m.eigensystem  in  src.contrib  can  lx; 
compiled  and  used  to  generate  the  eigen  values  ;uid  vectors. 

SEE  ALSO 

i.pca,  meigensystem,  r.mapcalc,  r.rescale,  ;ind  parser 

AUTHOR 

Michael  Shapiro.  U.S.  Army  Constniction  lingineering  Research  laboratory 
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NAME 

r.cross  -  Creates  a  cross  product  of  the  category  values  from  multipie  raster  map  layers. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxrosi 
r .cross  help 

r .cross  [-qz]  input  =name,ruime{  /tame,...]  output  name 
DESCRIPTION 

r.cross  creates  an  output  raster  map  layer  representing  all  unique  combinations  of  category  values  in 
the  raster  input  layers  (input  =name, name, name,  ...).  At  least  two,  but  not  more  than  ten,  input  map 
layers  must  be  specified.  The  user  must  also  specify  a  name  to  be  assigned  to  the  output  raster  map 
layer  created  by  r.cross. 

OPTIONS 

The  program  will  be  run  non- interactively  if  tile  user  specifies  the  names  of  between  2-10  raster  mup 
layers  be  used  as  input,  and  the  name  of  a  raster  map  layer  to  hold  program  output,  using  the  form: 

r.cross  [-qz]  mpat==name,narne[  flame,..]  output  name 

where  each  input  name  specifies  the  name  of  a  raster  map  layer  to  be  used  in  calculating  the  cross 
product,  the  output  name  specifies  the  name  of  a  raster  map  layer  to  hold  program  output,  and  the 
options  -q  and  -z  respectively  specify  that  the  program  is  to  run  quietly  and  exclude  zero  data  values. 

Alternately,  the  user  can  simply  type  r  .cross  on  the  command  line,  without  program  arguments.  In  this 
case,  the  user  will  be  prompted  for  needed  input  and  output  map  names  and  flag  settings  using  the 
standard  GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

Flags: 

-q  Run  quietly.  Supresses  output  of  program  percent-complete  messages.  If  this  flag 

is  not  used,  these  messages  are  printed  out. 

-z  Do  not  cross  zero  data  values.  This  means  that  if  a  zero  category  value  occurs  in 

any  input  data  layer,  the  combination  is  assigned  to  category  zero  in  the  resulting 
map  layer,  even  if  other  data  layers  contain  non-zero  data.  In  the  example  given 
above,  use  of  the  -z  option  would  cause  3  categories  to  be  generated  instead  of  5. 

If  the  -z  flag  is  not  specified,  then  map  layer  combinations  in  which  no!  all 
category  values  arc  zero  will  be  assigned  a  unique  category  value  in  the  resulting 
map  layer. 


Parameters: 

inpat  name,name\  flame ,...] 

The  names  of  between  two  and  ten  existing  raster  map  layers  to  be  used  as  input. 
Category  values  in  the  new  output  map  layer  will  be  the  cross-product  of  the 
category  values  from  these  existing  input  map  layers. 

output  -name  The  name  assigned  to  the  new  raster  map  layer  created  by  r. cross,  containing 
program  output. 
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EXAMPLE 

For  example,  suppose  that,  using  two  raster  map  layers,  the  following  combinations  occur: 


r.cross  would  produce  a  new  raster  map  layer  with  5  categories: 


Note:  The  actual  category  value  assigned  to  a  particular  combination  in  the  result  map  layer  is 
dependent  on  die  order  in  which  the  combinations  occur  in  the  input  map  layer  data  and  can  be 
considered  essentially  random.  The  example  given  here  is  illustrative  only. 

SUPPORT  FILES 

The  category  file  created  for  the  output  raster  map  layer  describes  the  combinations  of  input  map  layer 
category  values  which  generated  each  category,  hi  the  above  example,  the  category  labels  would  be: 

category  category 

value  label  _ 

1  layerl(O)  layer2(l) 

2  layerl(0)  layer2(2) 

3  layer!  (1)  layer2(l) 

4  layerl(l)  layer2(2) 

5  layer!  (2)  layer2(4) 


A  random  color  table  is  also  generated  for  the  output  map  layer. 

NOTES 

When  run  non  interactively,  r.cross  will  not  protect  existing  files  in  the  user’s  mapset.  If  the  user 
specifies  an  outpu:  file  name  that  already'  exists  in  his  mapset,  the  existing  file  will  be  overwritten  by 
the  new  r.cross  ixitput. 

SEE  ALSO 

r.corr,  r.covar,  r. slats,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Gins!  ruction  Iriginccring  Research  Istboraton 
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NAME 

r.describe  -  Prints  terse  list  of  category  values  found  in  a  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.describe 

r .describe  help 

r .describe  [-lrqd]  map  name 

DESCRIPTION 

r.describe  prints  a  terse  listir^  of  category  values  found  in  a  user- specified  raster  map  layer. 

Ihe  program  will  be  run  nun- interactively,  if  the  user  specifies  the  name  of  a  raster  map  layer  and  any 
desired  flags  on  the  command  line,  using  the  form 

r  .describe  [-lrqd]  map  name 

where  the  map  name  is  the  name  of  a  raster  map  layer  whose  categories  are  to  be  described,  and  the 
(optional)  flags  -7,  -r.  -q.  and  -d  have  the  meanings  described  below. 

Alternately,  the  user  can  simply  type  r  .describe  on  the  command  line,  without  program  arguments.  In 
tliis  case,  the  user  will  Ire  prompted  for  needed  flag  settings  and  the  parameter  value  using  the  standard 
GRASS  parser  interface  descrilxxl  in  the  manual  entry  for  parser. 

PROGRAM  USE 

Ihe  user  can  select  one  of  the  following  two  output  reports  from  r.describe : 

(1)  RANG1  A  range  of  category  values  found  in  the  raster  map  layer  will  be  printed.  The  range  is 
divided  into  three  groups:  negative,  positive,  and  zero.  If  negative  values  occur,  the  minimum  and 
maximum  negative  values  will  Ire  printed.  If  positive  values  occur,  the  minimum  and  maximum 
positive  values  will  Ire  printed.  If  zero  occurs,  this  will  be  indicated. 

(2)  LULL  LIST.  A  list  of  all  category  values  that  were  found  in  the  raster  map  layer  will  be  printed. 

Ihe  following  sample  (rut put  from  r.describe: 

0  2-4  10-13 

means  that  category  data  values  0,  2  through  4,  and  10  through  13  occurred  in  the  named  map  layer. 

Ihe  user  must  chcrose  to  read  the  map  layer  in  one  of  two  ways: 

(1)  D1R1XTI.Y.  Ihe  current  geographic  region  and  mask  are  ignored  and  the  full  raster  map  layer  is 
read.  Iliis  method  is  useful  if  the  user  intends  to  reclassify  or  rescale  the  data,  since  these  functions 
(r.rec.lass  and  r. rescale)  also  ignore  the  current  geographic  region  and  mask. 

(2)  RI  XilONI  J)  and  MASK  11 ).  Ihe  map  layer  is  read  within  the  current  geographic  region,  masked 
by  the  current  mask. 
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NON-INTERACTIVE  PROGRAM  USE 

r.describe  examines  a  user-chosen  raster  map  layer.  If  run  non-interactively,  the  layer  name  must  be 
supplied  on  the  command  line. 

A  compact  list  of  category  values  that  were  found  in  the  data  layer  will  be  printed. 

Following  is  a  sample  output: 

0  2-4  10-13 

-1  Print  the  output  one  value  per  line,  instead  of  the  default  short  form.  In  the  above  example, 
the  -1  option  would  output: 

0 

2 

3 

4 

10 

11 

12 

13 

-r  Only  print  the  range  of  the  data.  The  highest  and  lowest  positive  values,  and  the  highest  and 
lowest  negative  values,  are  output.  In  the  above  example,  the  -r  option  would  output: 

0  2  13 

If  the  -1  option  is  also  specified,  the  output  appears  with  one  category  value  per  line. 

-q  Qiiet.  The  -q  option  will  tell  r.describe  to  be  silent  while  reading  the  raster  file.  If  not 
specified,  program  percentage-completed  messages  are  printed. 

-d  Use  the  current  geographic  region  settings.  Normally,  r.describe  will  read  the  data  layer 
directly,  ignoring  both  the  current  region  settings  and  mask.  The  -d  option  tells  r.describe  to 
read  the  map  layer  in  the  current  region  masked  by  the  current  mask  (if  any). 

NOTES 

The  range  report  will  generally  run  faster  than  the  full  list. 

SEE  ALSO 

g.region,  rjnask,  r. reclass,  r. rescale  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  I aboratory 
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NAME 

r. drain  -  Traces  a  flow  through  an  elevation  model  on  a  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.drain 
r .drain  help 

rxlrain  input  =name  outpu t=name  [  coordinate  =a,y[,x,y ,...)] 

DESCRIPTION 

r.drain  traces  a  flew  through  a  least-cost  path  in  an  elevation  model.  The  elevation  surface  (a  raster 
map  layer  input)  might  be  the  cumulative  cost  map  generated  by  the  r.cost  program.  The  output  result 
(also  a  raster  map  layer)  will  show  one  or  more  least-cost  paths  between  each  user-prwided  locations) 
and  the  low  spot  (low  category  values)  in  the  input  model. 

The  program  will  be  run  non- interactively,  if  the  user  specifies  the  names  of  raster  map  layers  and  any 
desired  options  on  the  command  line,  using  the  form 

r .drain  input  name  output  =name  [coordinate  =or,y[,r,y ,...]] 

where  the  input  name  is  the  name  of  a  raster  map  layer  to  be  used  in  calculating  drainage,  the  output 
name  is  the  name  of  the  raster  map  layer  to  contain  output,  and  each  x,y  coordinate  pair  is  the 
geographic  location  of  a  point  from  which  drainage  is  to  be  calculated. 

Alternately,  the  user  can  simply  type  r.drain  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  needed  parameter  values  using  the  standard  GRASS  parser 
interface  described  in  the  manual  entry  for  parser. 

OPTIONS 

Program  parameters  are  as  follows. 

Parameters: 

input  =name  Name  of  raster  map  layer  containing  cell  cost  information, 

output  name  Name  of  raster  map  layer  to  contain  program  output, 

coordinate*,^  jc,y,...] 

Each  x,y  pair  is  the  easting  and  northing  (respectively)  of  a  starting  point  from 
which  a  least-cost  corridor  will  be  developed.  As  many  points  as  desired  can 
be  input.  (But,  see  BUGS  below.) 

EXAMPLE 

Consider  the  following  example: 

Input:  Qitput: 

Elevation  Surface  Least  Cost  Path 


20  | 

19  | 

17. 

16. 

17. 

16 

16.  .  . 

1.1.1. 

•  i 
18. 

18. 

24. 

18. 

15. 

12 

11. 

.  1 

22 

16. 

16. 

18. 

10. 

10 

10.  .  . 

.  1 

17. 

15. 

15. 

15. 

10. 

8 

8  .  . 

1  . 

24. 

16. 

8  . 

7  . 

8  . 

0 

12  .  .  . 

1  . 

17. 

9  . 

8  . 

7  . 

8  . 

6 

12  .  .  . 

The  user-provided  starting  location  in  tlx:  above  example  is  the  boxed  19  in  the  left-hand  map.  The 
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path  in  the  output  shows  the  least-cost  corridor  for  moving  from  the  starting  box  to  the  lowest 
(smallest)  possible  point.  This  is  the  path  a  raindrop  would  take  in  this  landscape. 

BUGS 

Currently,  r. drain  will  not  actually  provide  output  for  more  than  one  pair  of  input  coordinates  stated  on 
the  command  line. 

r.drain  also  currently  finds  only  the  lowest  point  (the  cell  having  the  smallest  category  value)  in  the 
input  file  that  can  be  reached  through  directly  adjacent  cells  that  are  less  than  or  equal  in  value  to  the 
cell  reached  immediately  prior  to  it;  therefore,  it  will  not  necessarily  reach  the  lowest  point  in  the  input 
file.  It  currently  finds  pits  in  the  data,  rather  than  the  lowest  point  present. 

Only  one  least-cost  path  is  currently  printed  to  the  output  file  for  the  user. 

Sometimes,  when  the  differences  among  cell  category  values  in  the  r.cost  cumulative  cost  surface 
output  are  small,  this  cumulative  cost  output  cannot  accurately  be  used  as  input  to  r.drain  ( r.drain  will 
output  bad  results).  This  problem  can  be  circumvented  by  making  the  differences  between  cell  category 
values  in  the  cumulative  cost  output  bigger.  It  is  recommended  that,  if  the  output  from  r.cost  is  to  be 
used  as  input  to  r.drain,  the  user  multiply  the  input  cost  surface  map  to  r.cost  by  the  value  of  the  map 
resolution,  before  running  r.cost.  This  can  be  done  using  r.mapcalc  or  other  programs.  The  map 
resolution  can  be  found  using  g.region. 

SEE  ALSO 

g.region,  r.cost,  r.mapcalc,  and  parser 

AUTHOR 

Kewan  Q.  Khawaja,  Intelligent  Engineering  Systems  laboratory,  M.I.T. 
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NAME 

r.grow  -  Generates  an  output  raster  map  layer  with  contiguous  areas  grown  by  one  cell  (pixel). 

(GRASS  Raster  Program) 

SYNOPSIS 

r.grow 
r^row  help 

r.grow  j-bq]  input  =name  output  =name 
DESCRIPTION 

r.grow  adds  one  cell  around  the  perimeters  of  all  areas  in  a  user- specified  raster  map  layer  and  stores 
the  output  in  a  new’  raster  map  layer. 

An  area  consists  of  any  contiguous  clump  of  cells  with  non-zero  category  values.  No  distinction  is 
made  between  differing  category  values  within  an  area.  Rather,  a  border  is  grown  around  the  outside  of 
each  entire  contiguous  set  of  non-zero  cells. 

The  output  raster  map  layer  will  not  go  outside  the  boundaries  set  in  the  current  geographic  region. 
Thus,  if  a  contiguous  area  in  the  input  raster  map  layer  extends  to  the  geographic  edge  of  the  current 
map  layer,  no  new  border  cells  can  be  added  to  that  side  of  the  area. 

Growth  around  a  rectangular  area  in  the  input  raster  map  layer  will  occur  straight  out  from  each  edge, 
but  not  diagonally  from  the  comers  of  the  rectangle.  Thus,  the  "grcwn"  border  area  will  contain  lines 
along  the  ed*e  of  the  original  rectangle,  but  the  comers  of  the  border  will  not  be  squared  off.  Instead, 
the  lines  of  the  border  that  go  along  each  side  of  the  original  rectangle  will  touch  only  at  the  comers  of 
the  cells  at  the  end  of  each  line. 

OPTIONS 

The  user  can  run  r.grow  either  interactively  or  non-interactively.  The  program  is  run  interactively  if 
the  user  types  r^row  without  specifying  flag  settings  and  parameter  values  on  the  command  line.  In 
this  case,  the  user  will  be  prompted  for  input. 

Alternately,  the  user  can  run  r.grow  non- interactively,  by  specifying  the  names  erf  an  input  and  output 
map  layer,  and  including  any  desired  flags,  on  the  command  line. 


Flags: 

-b 


-q 

Parameters: 
input  name 


output  =name 


Output  a  binary  raster  map  layer  having  only  zero-one  category  values,  regardless 
of  the  category  values  in  the  input  map  layer.  In  this  case,  all  cells  with  a  non¬ 
zero  category  value  in  the  input  map  layer  are  assigned  to  category  1  in  the 
output  map  layer.  If  the  -b  flag  is  not  used,  these  cells  will  retain  their  original 
non-zero  category  values.  In  either  case,  all  cells  whose  category  value  is 
changed  from  0  during  the  growing  process  are  assigned  a  category  value  of  1  in 
the  output  map. 

Run  quietly,  supressing  printing  of  information  about  program  progress  to 
standard  output. 


Name  of  an  existing  raster  map  layer  in  the  user’s  current  mapset  search  path 
containing  areas  to  lie  "grown." 

Name  of  the  new  raster  map  layer  to  contain  program  output.  This  map  will  be 
binary  if  the  user  sets  the  -b  flag.  Gherwisc,  input  map  cells  having  notv  zero 
category  values  will  retain  their  original  values.  In  either  case,  all  cells  whose 
values  changed  during  growth  will  be  assigned  category  value  1  in  die  output 
map. 
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NOTES 

The  r.grow  command  can  be  used  to  represent  the  boundary  of  one  or  more  areas.  In  this  case,  the 
zero-one  (binary)  output  option  should  NOT  be  used.  Ihen  the  input  map  layer  can  be  subtracted  from 
the  output  map  layer  using  the  rjnapcalc  command.  All  original  non-zero  category  values  will  be 
subtracted  out,  leaving  the  boundary’  areas  only.  This  resulting  zero-one  boundary  depiction  can  be 
displayed  over  other  related  raster  map  layers  using  the  overlay  option  of  d.rast. 

If  die  resolution  of  the  current  geographic  region  does  not  agree  with  the  resolution  of  the  input  raster 
map  layer,  unintended  resampling  of  the  original  raster  map  layer  may  occur.  The  user  should  lx;  sure 
that  the  current  geographic  region  is  set  property. 

SEE  ALSO 

d.rast,  g.region,  rjnapcalc,  r.poly 

AUTHOR 

Marjorie  Larson,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

r. in. ascii  -  Convert  an  ASCII  raster  text  file  into  a  (binary)  raster  map  layer. 

(GRASS  Raster  Data  Import  Program) 

SYNOPSIS  ' 

rjnjudi 
rJn-asdi  help 

rJnaiscii  Input  =name  output  name  [title  =“  phrase"} 

DESCRIPTION 

r.in.ascii  allows  a  user  to  create  a  (binary)  GRASS  raster  map  layer  from  an  ASCII  raster  input  file 
with  (optional)  title. 

COMMAND  LINE  OPTIONS 
Parameters: 

input  name  Name  of  an  existing  ASCII  raster  file  to  be  imported, 

output  -name  Name  to  be  assigned  to  resultant  binary  raster  map  layer, 

title  -"phrase"  Title  to  be  assigned  to  resultant  raster  map  layer. 

The  input  file  has  a  header  section  which  describes  the  location  and  size  of  the  data,  followed  by  the 
data  itself. 

The  header  has  6  lines: 

north:  xxxxxxjcx 

south:  xxxxxxjcx 

east:  xxxxxxjcx 

west:  xxxxxxjcx 

rows:  r 

cols:  c 

The  north,  south,  east,  and  west  field  values  entered  are  the  coordinates  of  the  edges  of  the  geographic 
region.  The  rows  and  cols  field  values  entered  describe  the  dimensions  of  the  matrix  of  data  to  follow. 
The  data  which  follows  is  r  rows  of  c  integers. 

EXAMPLE 

The  following  is  a  sample  input  file  to  r.in.ascii : 
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north: 

4299000.00 

south: 

4247000.00 

east: 

528000.00 

west: 

500000.00 

rows: 

10 

cds: 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

234 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

NOTES 

The  geographic  coordinates  north,  south,  east,  and  west  describe  the  outer  edges  of  the  geographic 
region.  They  ran  along  the  edges  of  the  cells  at  the  edge  of  the  geographic  region  and  NOT  through 
the  center  of  the  cells  at  the  edges. 

The  data  (which  follows  the  header  section)  must  contain  r  x  c  integers,  but  it  is  not  necessary  that  all 
the  data  for  a  row  be  on  one  line.  A  row  may  be  split  over  many  lines. 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.in.ll  ~  Converts  raster  data  referenced  using  latitude  and  longitude  coordinates  to  a  U1M- referenced 
map  layer  in  GRASS  raster  format. 

(GRASS  Raster  Data  Inport  Program) 

SYNOPSIS 

rinJl 
rinJl  help 

rJnJI  [  — s]  input  name  output  =name  bpc  =value  corner  =corner,lat,lon  dimension  rows, cols 
rts=latres,lonres  spheroid  =namt 

DESCRIPTION 

This  program  converts  raster  data  referenced  using  latitude  and  longitude  coordinates  to  a  UIM 
referenced  map  layer  in  GRASS  raster  format.  rJnJI  is  primarily  used  as  the  final  program  in 
converting  If  Hi)  and  DIM  digital  elevation  data  to  GRASS  raster  format,  but  is  not  limited  to  this 
use.  rjn.ll  uses  the  user’s  current  geographic  region  settings.  Only  data  that  falls  within  the  current 
geographic  region  will  appear  in  the  final  raster  map  layer. 

r.in.ll  requires  the  user  to  enter  the  following  information: 


COMMAND  LINE  OPTIONS 
Flags: 

-s  Signed  data  (high  bit  means  negative  v  alue). 


Parameters: 

input  -  name  Name  of  an  existing  input  raster  map  layer, 

output  name  Name  to  be  assigned  to  the  output  raster  map  layer, 

bpc  value  Number  of  bytes  per  cell. 

corner  =corner,lat,lort 

One  comer  latitude  and  longitude  of  the  input. 

Format:  {nw|  ne|  sw|  se},dd:mm:ss{N|  S},ddd:mm:ss{E|  W} 

The  latitude  and  longitude  are  specified  as  dd-nun.ssH  where  dd  is  degrees,  mm 
is  minutes,  ss  is  seconds,  and  H  is  the  hemisphere  (N  or  S  for  latitudes,  E  or  W 
for  longitudes). 

For  example,  to  specify  the  southwest  comer:  comer =sw ,46N,  120 W 

Note:  the  latitude  and  longitude  specified  are  for  the  carter  of  the  comer  cell, 
dimension  =r(yws,cols 

Number  of  rows  and  columns  in  the  input  file. 
res=latres,lonres  Resolution  of  the  input  (in  arc  seconds). 

spheroid  name  Name  of  spheroid  to  be  used  for  coordinate  conversion. 

Options:  airy,  australian,  bessel,  clark66,  everest,  grs80,  hayford,  international, 
krasovsky,  wgs66,  wgs72,  wgs84 

EXAMPLE 

Ihc  command  line: 


rjn.il  input  -rot  .out  output  =4mport.out  dimension  —358,301  bpc  =2  res=3,3 
corner  =sw  ,37: 1 3N, 103:45 W  spheroid  =wgs72 
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reads  data  from  the  file  rot. out,  converts  the  data,  and  stores  them  in  the  file  import. out.  The  data  to 
be  converted  are  made  up  of  358  rows  and  301  columns,  and  have  a  resolution  of  3x3  arc  seconds. 

NOTES 

In  the  conversion  of  I7TED  and  DEM  elevation  data  to  raster  map  layer  format,  r.in.ll  follows 
execution  of  the  data  rotation  program  m.rot90.  Because  the  user  can  glean  information  on  the  number 
of  rows  and  columns,  the  resolutions  of  the  latitude  and  longitude,  and  the  number  of  bytes  per  column 
from  the  header  file  produced  by  the  tape  extraction  programs  m.dted.extract  and  m.dmaUSGSread , 
the  user  should  recall  that  m.rol90  has  rotated  the  files  produced  by  the  tape  extraction  programs  90 
degrees;  this  means  that  the  user  should  IK  1 ERCI IANGE  the  numbers  of  rows  and  columns  present  in 
the  header  file  for  input  to  r.inJl.  Ihe  number  of  rows  shown  in  the  tape  extract  header  file  now 
become  the  number  of  columns  in  the  m.rol90  output  file;  the  number  of  columns  shown  in  the  tape 
extract  header  file  are  now  the  number  of  rows  present  in  the  m.rot90  output  file. 

The  user  should  also  note  that  the  raster  map  layer  imported  into  GRASS  will  be  based  on  the  current 
geographic  region  settings.  The  boundaries  of  this  geographic  region  should  therefore  be  checked 
before  importing  the  raster  map  layer.  Data  outside  of  the  geographic  region  will  not  be  imported  and 
missing  data  will  be  assigned  the  category  value  "no  data." 

SEE  ALSO 

nudmallSGSread,  mdted.examne,  m.dted.extract,  m.rot90 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.injunrast  -  Converts  a  SUN  raster  file  to  a  GRASS  raster  file. 

(GRASS  Raster  Data  Import  Program) 

SYNOPSIS 

rinsunrast 

DESCRIPTION 

This  program  converts  a  SUN  raster  file  that  has  been  created  by  SUN’S  "screendump"  utility  to  a 
GRASS  raster  file.  CXitput  is  placed  in  the  /cell  directory  under  the  user’s  current  GRASS  mapset. 

The  program  prompts  the  user  to  enter  the  name  of  the  SUN  raster  file  to  be  converted  and  the  name  to 
be  assigned  to  the  GRASS  raster  file  to  contain  the  resultant  image. 

It  is  recommended  that  this  program  be  used  in  an  x,y  database  (as  opposed  to,  for  example,  a  U1M 
data  base),  since  the  cell  header  is  created  with  nonsense  coordinates  (i.e.,  coordinates  designed  only  to 
specify  the  number  of  rows  and  columns  in  the  image).  Of  course,  the  user  can  adjust  the  cell  header 
after  import  using  r. support. 

The  user  must,  of  cause,  first  create  the  SUN  raster  file  to  be  converted,  either  by  running  the  SUN 
"screendump”  utility  (to  capture  a  displayed  image)  or  by  some  other  means  (e.g.,  from  a  scanning 
system  that  produces  SUN  raster  file  format). 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  src .alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

SUN  screendump  utility, 
r. support  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.infer  -  Outputs  a  raster  map  layer  whose  category  values  represent  the  application  of  user-specified 
criteria  (rales  statements)  to  other  raster  map  layers’  category  values. 

(GRASS  Raster  Program) 

SYNOPSIS 

rinfer 
rinfer  help 

rinfer  [-rt]  rulesfile  -name 
DESCRIPTION 

r.infer  is  an  inference  engine  which  applies  a  set  of  user-specified  rules  to  named  raster  map  layers.  A 
new  raster  map  layer  named  infer  is  created  as  output,  whose  category  values  reflect  the  ability  of  each 
cell  in  the  named  input  layers  to  satisfy  the  named  conditions. 

r.infer  commands  (conditions  and  consequences)  are  typed  into  a  file  by  the  user  using  a  system  editor 
like  vi,  and  then  input  to  r.infer  as  the  rulesfile  named  on  the  command  line.  The  results  are  used  to 
generate  a  new  raster  map  layer  named  infer  in  the  user’s  current  mapset.  This  program  performs 
analyses  similar  to  r. combine,  but  uses  a  (possibly)  more  pleasing  syntax  and  approach. 

OPTIONS 

The  program  will  be  ran  non-interactively  if  the  user  specifies  die  name  of  a  rales  file  and  any  desired 
flags  on  the  command  line,  using  the  form: 

rinfer  [-vt]  rulesfile  name 

where  name  is  the  name  of  an  ASCII  file  containing  valid  input  rales  to  r.infer ,  and  the  (optional)  flags 
-v  and  -/  have  the  meanings  described  in  the  OPTIONS  section,  below. 

Alternately,  the  user  can  simply  type  rinfer  on  the  command  line,  without  program  arguments.  In  this 
case,  the  user  will  be  prompted  for  the  needed  parameter  value  and  flag  settings  using  the  standard 
GRASS  parser  interface  described  in  the  manual  entry  for  parser. 

Flags: 

-t  Allows  the  user  to  ran  r.infer  in  test  mode.  The  user  is  questioned  about  the  truth  of  each 
condition  named  in  the  file,  r.infer  then  outputs  the  value  that  would  be  placed  in  the  new 
layer  infer  for  a  cell  meeting  conditions  specified  by  the  user.  When  no  sets  of  conditions 
stated  in  the  input  file  are  satisfied  (based  upon  the  user’s  answers),  cell  values  of  zero  are 
output.  Test  mode  is  used  to  test  the  accuracy  of  the  user’s  logic.  Users  are  encouraged  to  ran 
r.infer  in  test  mode  prior  to  actually  creating  map  layers. 

-v  Makes  r.infer  run  verbosely,  giving  information  about  each  cell  as  it  is  analyzed  accordiiig  to 
the  statement  conditions. 

Parameter: 

rulesfile 

Allows  the  user  to  input  rules  to  r. infer  from  an  ASCII  file,  rather  than  from  standard  input. 
This  ntlesfile  must  exist  in  the  user’s  current  working  directory  or  lie  given  by  its  full 
pathname.  File  rules  statements  take  the  same  fonn  as  those  given  on  the  command  line. 
Examples  of  valid  rules  statements  are  given  in  the  sections  below. 
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COMMANDS  AND  STATEMENTS 

The  following  commands  are  available  in  r. infer: 


Command 

Aliases 

Followed  By 

Such  As 

IFMAP 

ANDIFMAP 

ANDMAP 

cellmap  cat# 

geology  2 

IFNOTMAP 

ANDNOTMAP 

ceilmap  cat# 

geology  2 

THENMAPIIYP 

cat#  [statement] 

3  nice  vacation  spot 

THEN 

statement 

condition 

No  sandstone 

IE 

AND 

ANDIE 

predefined 
statement  condition 

No  sandstone 

These  five  commands  may  be  used  to  formulate  statements  with  functions  ranging  from  a  simple 
reclassification  to  a  more  complex  expert  system  type  application.  Statements  are  composed  of  erne  or 
more  conditions  followed  by  one  or  more  hypotheses  and/or  conclusions.  The  use  of  aliases  is 
provided  to  allow  for  the  use  of  a  command  which  has  an  English  meaning  consistent  with  the  logic  at 
that  point. 

Following  is  a  description  of  each  of  the  five  commands.  The  map  layers  used  in  the  examples  are  in 
the  Spearfish  sample  data  base. 

IFMAP 

Map  condition. 

Map  conditions  are  questions  to  each  cell  about  the  presence  of  specified  map  layer  category  values. 
r.infer  questions  each  cell  in  the  named  map  layer  (here,  geology)  about  its  contents  (i.e.,  category 
value),  (ills  which  satisfy  the  named  condi tion(s)  stated  by  IFMAP  (i.e.,  here,  those  cells  which 
contain  geology  map  layer  category  values  4  or  5)  will  be  assigned  the  subsequently-stated  map 
conclusion  or  hypothesis  (category),  in  the  new  map  layer  infer.  Cells  which  fail  to  satisfy  named  map 
condition(s)  will  continue  to  move  down  through  the  user’s  rulesfUe  (searching  for  conditions  it  is  able 
to  satisfy)  if  any  additional  conclusions/hypotheses  are  stated  in  the  file,  or  will  be  assigned  category 
zero  in  the  new  map  layer  infer  (if  no  additional  conclusions/hypotheses  are  possible  in  this  rulesfUe). 

example:  IFMAP  geology  4  5 


IFNOTMAP 

Map  condition. 

like  IFMAP,  but  instead  questions  each  cell  about  the  absence  of  specified  map  layer  categories.  Cells 
which  meet  the  IFN01MAP  conditions  (i.e.,  below,  those  cells  which  do  NOT  include  owner  map  layer 
category  value  2)  will  be  assigned  the  named  conclusionothcsis,  in  tire  new  map  layer  infer. 

example:  IFNOTMAP  owner  2 


11 IENMAPI1YP 
Map  conclusion. 

Assigns  each  cell  a  specified  category  value  in  the  new  map  layer  infer  based  on  the  cell’s  ability  or  failure 
to  meet  conditions  named  above  this  THENMAPHYP  statement  in  the  rulesfUe.  Tlte  user  sluxtld  note 
that  although  the  user  can  specify  a  tuiiquely-named  rulesfile,  r.infer  always  directs  its  output  to  a  File 
named  infer  in  the  current  mapset  (overwriting  whatever  is  currently  in  this  file),  llierefore,  if  tlic  user 
wishes  to  save  this  file  lor  future  use,  this  file  sluxtld  lx:  renamed  before  tlie  user  next  nms  r.infer  (c.g  , 
using  the  GRASS  command  g. rename). 
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It  is  important  to  realize  that  r.infer  runs  through  the  conditions  stated  in  the  named  rule  <; file  one  cell 
at  a  time,  moving  from  the  top  of  the  raster  input  file  to  the  bottom  of  the  raster  input  file.  As  soon  as 
the  cell  currently  being  examined  by  r.infer  satisfies  a  set  of  conditions,  it  is  assigned  a  category  value 
in  the  new  map  layer  infer,  r. infer  does  NOT  check  to  see  if  that  same  cell  satisfies  other  conditions 
named  further  down  in  the  input  file,  too.  Instead  it  moves  on  to  the  next  cell,  and  begins  anew  with 
the  conditions  named  at  the  top  of  the  input  file.  Essentially,  this  means  that  conclusions  made  higher- 
14?  in  the  input  file  have  precedence  over  conditions  named  further  down  in  the  input  file. 

example:  IfMAl*  density  1 

THENMAPHYP  1  no  trees 

In  the  above  example,  all  cells  having  a  category  value  of  1  (non-forest)  in  the  map  layer  density,  are 
assigned  a  category  vain*'  of  /  in  the  resultant  map  layer  infer.  7 he  trailing  text  "no  trees”  is  entered 
into  the  category  support  ule  for  category  1  in  the  new  map  layer  infer. 

THEN 

Statement  hypothesis. 

At  the  conclusion  of  one  or  several  condition  statements,  instead  of  making  a  map  conclusion  as  with 
THENMAPHYP,  the  conditions  are  used  to  create  a  hypothesis.  This  may  then  be  referenced  in  later 
statements  using  the  IF  command.  The  trailing  text  at  the  end  of  the  THEN  statement  is  used  as  the 
means  with  which  to  reference  the  hypothesis.  An  example  follows  the  descripti.  n  of  IF  below. 


IF 

Statement  condition. 

States  a  condition  based  on  an  hypothesis  that  was  created  by  a  previous  THEN  statement.  IF  may  be  used 
only  after  a  THEN  has  set  up  the  group  of  statements  that  are  to  be  referenced  later. 

example:  IFMAP  elevation .255  170-255 
ANDIFMAP  density  3  4 
THEN  high  elevation  with  trees 
1 

IF  high  elevation  with  trees 
ANDIFMAP  owner  2 
THENMAPHYP  1  this  is  the  place 

The  above  example  queries  each  cell  for  the  presence  of  both  elevations  greater  than  15&0  meters  (i.e., 
for  elevation255  category  values  170-255)  and  a  medium  to  high  density  of  trees  (i.e.,  density 
category'  values  3  4).  All  areas  (i.e.,  cells)  that  satisfy  these  criteria  are  assigned  to  the  hypothesis 
"high  elevation  with  trees."  The  ”!"  simply  tells  r.infer  to  ignore  whatever  appears  on  that  line  (a 
comment  statement),  and  is  used  here  for  readability. 

The  IF  statement  then  references  cells  living  "high  elevation  with  trees"  (i.e.,  those  cells  that  satisfied 
both  of  the  above  condition  ,  named  by  the  IFMAP  and  ANDIFMAP  statements).  If  a  cell  both  has 
"high  elevations  with  trees"  and  owner  map  layer  category  2  (areas  .vned  by  the  Forest  Service),  it  is 
assigned  by  tire  THENMAPHYP  statement  to  category  1  in  the  new  map  layer  infer.  The  trailing  text 
"this  is  the  place"  is  automatically  entered  into  the  category  support  file  for  the  new  map  infer.  Cells 
failing  to  meet  all  of  the  coixlitions  stated  in  this  input  file  will  be  assigned  category  0  in  the  new  map 
layer  infer. 

SEE  ALSO 

GRASS  Tutorial:  r.infer 

g. rename,  r. combine,  r.mapcalc,  r. weight,  and  parser 
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AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory 

fecial  recognition  goes  to: 

George  W.  Hageman 
SOFTMAN  Enterprises 
P.O.  Box  11234 
Boulder,  Colorado  80301 

Daniel  S.  Cox 
In  Touch 

796  West  Peachtree  St.  NE 
Atlanta,  GA  30308 

Mr.  Hageman,  in  the  spring  of  1986,  submitted  an  inference  engine  to  the  UNIX  network.  Mr.  Cox 
reworked  the  code  submitting  an  new  version  shortly  thereafter.  It  is  this  code  that  forms  die  basis  for 
r.infer. 
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NAME 

r.info  -  Outputs  basic  information  about  a  user-specified  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

rJnfo 
r  Jnfo  help 
rinfo  map  =name 

DESCRIPTION 

r.info  reports  some  basic  information  about  a  user- specified  raster  map  layer,  lhis  map  layer  must 
exist  in  the  user’s  current  mapset  search  path.  Information  about  the  map's  boundaries,  resolution, 
projection,  data  ripe,  category  number,  data  base  location  and  mapset,  and  history  are  put  into  a  table 
and  written  to  standard  output.  The  types  of  information  listed  can  also  be  found  in  the  /cats,  /cellhd. 
and  /hist  directories  under  the  mapset  in  which  the  named  map  is  stored. 

The  program  will  be  run  non- interactively  if  the  user  specifies  lire  name  of  a  raster  map  layer  on  the 
command  line,  using  the  form: 

rJnfo  map  name 

where  name  is  the  name  of  a  raster  nap  layer  on  which  the  user  seeks  information.  The  user  can  save 
the  tabular  output  io  a  file  In  using  the  UNIX  redirection  mechanism  (<);  for  example,  tlte  user  might 
save  a  report  on  the  soils  map  layer  in  a  file  called  soil.rpt  by  typing: 

rJnfo  map^soils  >  soil .rpt 

Alternately,  the  user  can  simply  type  r.info  on  the  command  line,  without  program  arguments.  In  this 
case,  the  user  will  be  prompted  for  the  name  of  a  raster  map  layer  using  the  standard  GIUVSS  parser 
interface  described  in  the  manual  entry  for  parser  Ihe  user  is  asked  whether  he  wishes  to  print  the 
report  and/or  save  it  in  a  file.  If  saved,  the  rejxul  is  stored  in  a  user- named  file  in  the  user’s  home 
director  .  liek-.v  is  the  report  produced  by  r.info  for  tlx;  raster  map  geology  in  the  Spearfish  sample 
data  Ut.se. 


layer:  geology  Date:  Mon  May  4  10:00:14  1987 
Location:  spearfish  Digit)  of  Creator:  grass 
Mapset:  PERMANLNT 

Title:  Geology _ 

Type  of  Map:  raster  Number  of  Categories:  9 

Rows:  140 

Columns:  190 

Total  Cells:  26600 

Projection:  DIM  (zone  13) 

N:  4928000.00  S:  4914000.(X)  Res:  100.00 
I  :  609000.00  W:  590000.00  Res:  100.00 

Data  Source: 

Raster  file  produced  liy  L.ROS  llnta  Center 
Data  I  Ascription: 

Shows  the  geology  for  the  map  area 
Comments: 
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SEE  ALSO 

g.mapsets,  rxoin,  r. describe,  r. report,  rjtats,  r support,  r.what,  and  parser 
AUTHOR 

Michael  O'Shea,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.line  -  Makes  a  new  binary  GRASS  vector  file  by  extracting  line  features  from  a  thinned  raster  file. 
(GRASS  Raster  Program) 

SYNOPSIS 

rJine 
rJine  help 

rJine  input  name  output  =name  [type=iui/ne] 

DESCRIPTION 

r.line  scans  the  named  raster  map  layer  (input  =name)  and  extracts  thinned  linear  features  into  the 
named  vector  file  (output  -name).  rJine  assumes  that  the  input  map  has  been  thinned  using  r.thin. 

OPTIONS 

The  user  can  run  this  program  either  non-interactively  or  interactively.  The  program  will  be  run  non- 
interactively  if  the  user  specifies  program  arguments  on  the  command  line,  using  the  form: 

rJine  input  =name  output  -name  [typ *=name] 

If  the  user  specifies  input  raster  and  output  vector  map  names  on  the  command  line,  any  other 
parameter  values  left  unspecified  on  the  command  line  will  be  set  to  their  default  values  (see  below). 
Alternately,  the  user  can  simply  type  rJine  on  tlie  command  line,  without  program  arguments.  In  this 
case,  the  user  will  be  prompted  for  parameter  values  using  the  standard  GRASS  parser  interface 
described  in  the  manual  entry  for  parser. 

Parameters: 

input  name  Name  of  existing  raster  file  to  be  used  as  input, 

output  name  Name  of  new  vector  file  to  be  output. 

typ *=name  line  type  of  the  extracted  vectors:  either  line  or  area.  Specifying  line  will  type 

extracted  vectors  as  linear  edges.  Specifying  area  will  type  extracted  vectors  as 
area  edges. 

Options:  line  or  area 
Default:  type  Mine 

NOTES 

r.line  extracts  vectors  (aka,  "arcs")  from  a  raster  file.  These  arcs  may  represent  linear  features  (like 
roads  or  streams),  or  may  represent  area  edge  features  (like  political  boundaries,  or  soil  mapping  units). 
The  attribute  type  option  allows  the  user  to  establish  the  use  of  either  linear  or  area  edge  attributes  for 
all  of  the  extracted  vectors. 

r.poly  may  be  used  to  extract  vectors  that  represent  area  features  (like  soil  mapping  units,  elevation 
ranges,  etc.)  from  a  raster  file. 

The  user  must  run  v support  on  the  resultant  vector  (v. digit)  files  to  build  the  dig_plus  information. 

r.thin  and  r.line  may  create  excessive  nodes  at  every  junction,  and  may  create  small  spurs  or  "dangling 
lines"  during  thinning  and  vectorization.  These  nodes  and  spurs  may  be  removed  using  vjrim. 

This  program  remains  under  alpha  testing.  It  resides  in  the  src. alpha  directory  and  must  be  compiled 
separately  by  the  user. 

BUGS 

The  input  raster  file  MUST  be  thinned  by  r.thin\  if  not,  rJine  may  crash. 

SEE  ALSO 

r.poly,  r.thin,  v. digit,  v. support,  v.trim,  and  parser 

AUTHOR 

Michael  Baba,  DBA  Systems,  Inc.,  10560  Arrowhead  Drive,  Fairfax,  Virginia  22030 
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r.los  -  Line-of-sight  raster  analysis  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

rJos 

r  Jos  help 

rJos  input  =name  <Hitput  =name  coordinate  =x,y  [putt  map  name]  [obs  elev  =value] 

[  maxdist  —value] 

DESCRIPTION 

r.los  generates  a  raster  map  output  in  which  the  cells  that  are  visible  from  a  user-specified  observer 
fixation  are  marked  with  integer  values  that  represent  the  vertical  angle  (in  degrees)  required  to  see 
those  cells. 

lhe  program  can  lie  run  either  non-interactively  or  interactively.  To  run  r.los  non-interactively,  the 
user  must  specify  at  least  an  input  file  name,  output  file  name,  and  the  geographic  coordinates  of  the 
user's  viewing  fixation  on  the  command  line;  any  remaining  parameters  whose  vtdues  are  unspecified 
on  the  command  line  will  lie  set  to  their  default  values  (see  below).  Non-interactive  usage  format  is: 

rJos  input  =name  output  name  coordinate  x,y  [patt_map=/io/ne]  [obs_dev  =value] 

[  max  dist  =value  ] 

Alternately,  the  user  can  type  simply  r Jos  on  the  command  line;  in  this  case,  the  program  will  prompt 
the  user  for  parameter  values  using  the  standard  GRASS  interface  described  in  the  manual  entry  for 
parser. 


Parameters: 


input —name 
output  =name 
coordinate  —X,y 

patt  map  -name 


obs_  elev  —value 
max_dist  =value 


Name  of  a  raster  map  layer  containing  elevation  data,  used  as  program  input. 

Name  assigned  to  the  file  in  which  the  raster  program  output  will  be  stored. 

Geographic  coordinates  (i.e.,  easting  and  northing  values)  identifying  the  desire* 
location  of  the  viewing  point. 

Name  of  a  binary  (1A))  raster  map  layer  in  which  cells  within  the  areas  of  interest 
are  assigned  the  category  value  ’T,  and  all  other  cells  are  assigned  the  category 
value  ’O’.  If  this  parameter  is  omitted,  the  analysis  will  be  performed  for  the 
whole  area  within  a  certain  distance  of  the  viewing  point  inside  the  geographic 
region  boundaries. 

Default:  assign  all  cells  that  are  within  the  max_disl  and  within  the  user’s 
current  geographic  region  boundaries  a  value  of  1 . 

Height  of  the  observer  (in  meters)  above  the  viewing  point’s  elevation. 

Default:  1 .75  (meters) 

Maximum  distance  (in  meters)  from  the  viewing  point  inside  of  which  the  line  of 
sight  analysis  will  be  performed.  The  cells  outside  this  distance  range  are 
assigned  the  category  value  ’O’. 

Options:  0-99999  (stated  in  map  units) 

Default:  100 


NOTKS 

lor  accurate  results,  the  program  must  be  rnn  with  the  resolution  of  the  geographic  region  set  equal  to 
the  resolution  of  the  data  (see  g.region). 


It  is  advisaMc  to  use  a  ’ pattern  layer1  that  identifies  the  areas  of  interest  in  which  the  line  of  sight 
analysis  is  required.  Such  a  measure  will  reduce  tlx:  time  taken  by  the  program  to  run. 
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SEE  ALSO 

g.region,  r. pat. place,  and  parser 

AUTHOR 

Kewan  Q.  Khawaja,  Intelligent  Engineering  Systems  Laboratory,  M.I.T. 


GRASS  4.0  (Summer  1991) 


U  S  Anm  (ERL 


r.mapcalc 


GRASS  Reference  Manual 


rmapcaJc 


NAME 

r.mapcalc  -  Raster  map  layer  data  calculator. 

(GRASS  Raster  Program) 

SYNOPSIS 

r  anapcsdc 

r  jnapcalc  [result  ^expression] 

DESCRIPTION 

r.mapcalc  performs  arithmetic  on  raster  map  layers.  New  raster  map  layers  can  be  created  that  are 
arithmetic  expressions  involving  existing  raster  map  layers,  integer  or  floating  point  constants,  and 
functions. 

PROCRAM  USE 

If  used  without  command  line  arguments,  r.mapcalc  will  read  its  input,  one  line  at  a  time,  from 
standard  input  (which  is  the  keyboard,  unless  redirected  from  a  file  or  across  a  pipe).  Otherwise,  the 
expression  on  the  command  line  is  evaluated.  r.mapcalc  expects  its  input  to  have  the  form: 

result  = expression 

where  result  is  the  name  of  a  raster  map  layer  to  contain  the  result  of  the  calculation  and  expression  is 
any  legal  arithmetic  expression  involving  existing  raster  map  layers,  integer  or  floating  point  constants, 
and  functions  known  to  the  calculator.  Parentheses  are  allowed  in  the  expression  and  may  be  nested  to 
tiny  depth,  result  will  be  created  in  the  user’s  current  mapset. 

'I he  formula  entered  to  r.mapcalc  by  the  user  is  recorded  both  in  the  result  map  title  (which  appears 
in  the  category  file  for  result)  and  in  the  history  file  for  result. 

Some  characters  have  special  meaning  to  the  command  shell.  If  the  user  is  entering  input  to  rjnapcalc 
on  the  command  line,  expressions  should  be  enclosed  within  single  quotes.  See  NOTTS,  below. 

OPERATORS  AND  ORDER  OE  PRECEDENCE 

Ihe  following  operators  are  supported: 


Operator 

Meaning 

Type 

Precedence 

% 

modulus  (remainder  upon  division) 

Arithmetic 

4 

/ 

division 

Arithmetic 

4 

* 

multiplication 

Arithmetic 

4 

+ 

addition 

Arithmetic 

3 

subtraction 

Arithmetic 

3 

=  = 

equal 

Logical 

O 

Am 

1  __ 

not  equal 

logical 

2 

> 

greater  than 

Logical 

O 

Am 

>= 

greater  than  or  equal 

Logical 

"> 

< 

less  than 

Logical 

Am 

<= 

less  than  or  equal 

Logical 

2 

Me 

and 

Logical 

i 

II 

or 

logical 

i 

I  he  operators  are  applied  from  left  to  right,  with  those  of  higher  precedence  applied  before  those  with 
lower  precedence.  Division  by  0  and  modulus  by  0  are  acceptable  and  give  a  0  result.  The  logical 
operators  give  a  1  result  if  the  comparison  is  tme,  0  otherwise. 
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RASTER  MAP  LAYER  NAMES 

Anything  in  the  expression  which  is  not  a  number,  operator,  or  function  name  is  taken  to  be  a  raster 
map  layer  name.  Examples: 

elevation  x3  3d.his 

Most  GRASS  raster  map  layers  meet  this  naming  convention.  However,  if  a  raster  map  layer  has  a 
name  which  conflicts  with  the  above  rule,  it  should  be  quoted.  For  example,  the  expression 

x  =  a-b 

would  be  interpreted  as:  x  equals  a  minus  b,  whereas 
x  =  "a-b" 

would  be  interpreted  as:  x  equals  the  raster  map  layer  named  a-b 
Also 


x  =  3107 

would  create  x  filled  with  the  number  3107,  while 
x  = "3107" 

would  copy  the  raster  map  layer  3107  to  the  raster  map  layer  x. 

Oiotes  are  not  required  unless  the  raster  map  layer  names  look  like  numbers  or  contain  operators,  OR 
unless  the  program  is  run  non-interactivcly .  Examples  given  here  assume  the  program  is  run 
interactively.  See  NOTES,  below. 

r.mapcalc  will  look  for  the  raster  map  layers  according  to  the  user’s  current  mapset  search  path.  It  is 
possible  to  override  the  search  path  and  specify  the  mapset  from  which  to  select  the  raster  map  layer. 
Ibis  is  done  by  specifying  the  raster  map  layer  name  in  the  form: 

name@mapset 

For  example,  the  following  is  a  legal  expression: 
result  =  x@PERMANENT  /  y@SQLLS 

Ihe  mapset  specified  does  not  have  to  be  in  the  mapset  search  path.  (This  method  of  overriding  the 
mapset  search  path  is  common  to  all  GRASS  commands,  not  just  rjnapcalc.) 


THE  NEIGHBORHOOD  MODIFIER 

Maps  and  images  are  data  base  files  stored  in  raster  format,  i.e.,  two-dimensional  matrices  of  integer 
values.  In  r.mapcalc,  maps  may  be  followed  by  a  neighborhood  modifier  that  specifies  a  relative 
offset  from  the  current  cell  being  evaluated.  The  format  is  map[r,c],  where  r  is  the  row  offset  and  c  is 
the  column  offset.  For  example,  map!  1,2 ]  refers  to  the  cell  one  row  below  and  two  columns  to  the 
right  of  the  current  cell,  map{-2,-l ]  refers  to  the  cell  two  rows  abwe  and  one  column  to  the  left  of  the 
current  cell,  and  mapl0,l]  refers  to  the  cell  one  column  to  the  right  of  the  current  cell.  Ibis  syntax 
permits  the  development  of  neighborhood-type  filters  within  a  single  map  or  across  multiple  maps. 
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RASTER  MAP  LAYER  VALUES  FROM  THE  CATEGORY  FILE 

Sometimes  it  is  desirable  to  use  a  value  associated  with  a  category’s  contents  instead  erf  the  category 
value  itself.  If  a  raster  map  layer  name  is  preceded  by  the  @  operator,  then  the  labels  in  the  category 
file  for  the  raster  map  layer  are  used  in  the  expression  instead  of  the  category  value. 

For  example,  suppose  that  the  raster  map  layer  soil.ph  (representing  soil  pH  values)  has  a  category  file 
with  labels  as  follows: 

cat  label 

0  no  data 

1  1.4 

2  2.4 

3  3.5 

4  5.8 

5  7.2 

6  8.8 

7  9.4 

Then  the  expression: 

result  =  (ffisoils.ph  *  10 

would  produce  a  result  with  category  values  0,  14,  24,  35,  58,  72,  88  and  94. 

Note  that  this  operator  may  only  be  applied  to  raster  map  layers  and  produces  a  floating  point  value  in 
the  expression.  Also  the  category  label  must  start  with  a  valid  number.  Missing  labds,  or  labels  that 
do  not  start  with  a  number  will  (silently)  produce  a  0  value  for  that  category. 

GREY -SCALE  EQUIVALENTS  AND  COLOR  SEPARATES 

It  is  often  helpful  to  :  anipulate  the  colors  assigned  to  map  categories.  This  is  particularly  useful  when 
the  spectral  properties  of  cells  have  meaning  (as  with  imagery  data),  or  when  the  map  category  values 
represent  real  quantities  (as  when  category’  values  reflect  true  elevation  values).  Map  color 
manipulation  can  :ilso  aid  visual  recognition,  and  map  printing. 

The  #  operator  can  be  used  to  either  convert  map  category  values  to  their  grey  scale  equivalents  or  to 
extract  the  red,  green,  or  blue  components  of  a  raster  map  layer  into  separate  raster  map  layers. 

result  =  Anap 

converts  each  category  value  in  map  to  a  value  in  the  range  0-255  which  represents  the  grey  scale  level 
implied  by  the  color  for  the  category.  If  the  map  has  a  grey-scale  color  table,  then  the  grey  level  is 
wiiat  Mnap  evaluates  to.  Otherwise,  it  is  computed  as: 

.18  *  red  +  .81  «  green  +  .01  *  blue 

The  #  operator  has  three  other  forms:  r#nap,  g#nap,  btfcnap.  These  extract  the  red,  green,  or  blue 
components  in  the  named  raster  map,  respectively.  The  GRASS  shell  script  blendsh  extracts  each  erf 
these  components  from  two  raster  map  layers,  and  combines  them  by  a  user-specified  percentage. 
These  fonns  allow  color  separates  to  be  made.  For  example,  to  extract  the  red  component  from  map 
and  store  it  in  the  new  0  255  map  layer  red,  the  user  could  type: 

red  =  rftnap 

lb  assign  this  map  grey  colors  type: 

rcolors  map=red  color  =mles 

black 

white 
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To  assign  thus  map  red  colors  type: 

r.coiors  map=red  color  =rules 

black 

red 


FUNCTIONS 

The  functions  currently  supported  are  listed  in  the  table  below.  The  type  of  the  result  is  indicated  in 
the  last  column.  F  means  that  the  functions  always  results  in  a  floating  point  value,  /  means  that  the 
function  gives  an  integer  result,  and  *  indicates  that  the  result  is  float  if  any  of  the  arguments  to  the 
function  are  floating  point  values  and  integer  if  all  arguments  are  integer. 

function _ description _ type 


abs(x) 

return  absolute  value  of  x 

* 

atan(x) 

inverse  tangent  of  x  (result  is  in  degrees) 

F 

cos(x) 

cosine  of  x  (x  is  in  degrees) 

F 

exp(x) 

exponential  function  of  x 

F 

exp(x,y) 

x  to  the  pewer  y 

F 

float(x) 

convert  x  to  floating  point 

F 

if 

decision  options: 

* 

if(x) 

1  if  x  not  zero,  0  otherwise 

if(x-a) 

a  if  x  not  zero,  0  otherwise 

if(x,a,b) 

a  if  x  not  zero,  b  otherwise 

if(x,a,b,c) 

a  if  x  >0,  b  if  x  is  zero,  c  if  x  <0 

int(x) 

convert  x  to  integer  [  truncates  ] 

I 

log(x) 

natural  log  of  x 

F 

log(xb) 

log  of  x  base  b 

F 

max(x,y[  ,z...]) 

largest  value  of  those  listed 

* 

nrin(x,y[/...)) 

smallest  value  erf  those  listed 

* 

tound(x) 

round  x  to  nearest  integer 

I 

sin(x) 

sine  of  x  (x  is  in  degrees) 

F 

sqrt(x) 

square  root  of  x 

F 

tan(x) 

tangent  of  x  (x  is  in  degrees) 

F 

FLOATING  POINT  VALUES  IN  THE  EXPRESSION 

Floating  point  numbers  are  allowed  in  the  expression.  A  floating  point  number  is  a  number  that 
contains  a  decimal  point: 

23  12.  m 

Floating  point  values  in  the  expression  are  handled  in  a  special  way.  With  arithmetic  and  logical 
operators,  if  either  operand  is  float,  the  other  is  converted  to  float  and  the  result  of  the  operation  is  float. 
This  means,  in  particular  that  division  of  integers  results  in  a  (truncated)  integer,  while  division  erf  floats 
results  in  an  accurate  floating  paint  value.  With  functions  of  type  *  (see  table  above),  the  result  is  float 
if  any  argument  is  float,  integer  otherwise. 

However,  GRASS  raster  map  layers  can  only  store  integer  values.  If  the  final  value  of  the  expression  is 
a  floating  point  value,  this  value  is  rounded  to  the  nearest  integer  before  storing  it  in  the  result  raster 
map  layer. 

Note  that  raster  map  layers  in  the  expression  are  considered  to  be  integers. 
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EXAMPLES 

I’o  compute  the  average  of  two  raster  map  layers  a  and  b : 

ave  =  (a  +  b)/2 
To  form  a  weighted  average: 

ave  =  (5*  a  +  3*b)/8.0 

To  produce  a  binaiy  representation  of  the  raster  map  layer  a  so  that  category  0  remains  0  and  all  other 
categories  become  1 : 

mask  =  a/a 

This  could  also  be  accomplished  by: 
mask  =  if(a) 

To  mask  raster  map  layer  b  by  raster  map  layer  a: 
result  =  if(ab) 

REGION/MASK 

The  user  must  be  aware  of  the  current  geographic  region  and  current  mask  settings  when  using 
r.ntapcalc.  All  raster  map  layers  are  read  into  the  current  geographic  region  masked  by  the  current 
mask.  If  it  is  desired  to  modify  an  existing  raster  map  layer  without  involving  other  raster  map  layers, 
the  geographic  region  should  be  set  to  agree  with  the  cell  header  for  the  raster  map  layer.  For  example, 
suppose  it  is  determined  that  the  elevation  raster  map  layer  must  have  each  category  value  increased 
by  10  meters.  The  following  expression  is  legal  and  will  do  the  job: 

new_elevation  =  elevation  +  10 

Since  a  category  value  of  zero  is  used  in  GRASS  for  locations  that  do  not  exist  in  the  raster  map  layer, 
the  new  raster  map  layer  will  contain  the  category  value  10  in  the  locations  that  did  not  exist  in  the 
original  elevation.  Therefore,  in  this  example,  it  is  essential  that  the  boundaries  of  the  geographic 
region  be  set  to  agree  with  the  cell  header.  Hew  ever,  if  there  is  a  current  mask,  then  the  resultant 
raster  map  layer  is  masked  when  it  is  written;  i.e.,  zero  category  values  in  the  mask  force  zero  values  in 
the  output. 

NOTES 

Fxtra  care  must  lie  taken  if  the  expression  is  given  on  the  command  line.  Some  characters  have  special 
meaning  to  the  UNIX  shell.  These  include,  among  others: 

*()>&| 

It  is  advisable  to  put  sirgle  quotes  around  the  expression;  eg.: 
result  =  ’elevation  *  2’ 

Without  the  quotes,  the  *,  which  has  special  meaning  to  the  UNIX  shell,  would  be  altered  and 
r.mapcalc  would  see  something  other  than  the  * . 

If  the  input  comes  directly  from  the  keyboard  and  the  result  raster  map  layer  exists,  the  user  will  be 
asked  if  it  can  be  overwritten.  Otherwise,  the  result  raster  map  layer  will  automatically  lie  overwritten 
if  it  exists. 
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Quoting  result  is  not  allowed.  I  lowever,  it  is  never  necessary  to  quote  result  since  it  is  always  taken 
to  be  a  raster  snap  layer  name. 

For  formulas  that  the  user  enters  from  standard  input  (rather  than  from  the  command  line),  a  line 
continuation  feature  now  exists.  If  the  user  adds  \  to  the  end  of  an  input  line,  rjnapcalc  assumes  that 
the  formula  being  entered  by  the  user  continues  on  to  the  next  input  line.  Ihere  is  no  limit  to  the 
possible  number  of  input  lines  or  to  the  length  of  a  formula. 

If  the  rjnapcalc  formula  entered  by  the  user  is  very  long,  the  map  title  will  contain  only  some  of  it, 
but  most  (if  not  all)  of  the  fonnula  will  be  placed  into  the  history  file  for  the  result  map. 

When  the  user  enters  input  to  r.mapcalc  non-interactiveiy  on  the  command  line,  the  program  will  not 
warn  the  user  not  to  overwrite  existing  map  layers.  Users  should  therefore  take  care  to  assign  program 
outputs  raster  file  names  that  do  not  yet  exist  in  their  current  mapsets. 

SEE  ALSO 

" r.mapcalc :  An  Algebra  for  GIS  and  Image  Processing,"  by  Michael  Sltapiro  and  James  Westervelt, 
U.S  Army  Construction  Engineering  Research  laboratory  (March  1991). 

"GRASS  Tutorial:  rjnapcalc"  by  Maiji  1  arson,  U.S.  Anny  Construction  lingineering  Research 
Laboratory. 

Grey  scale  conversion  is  based  on  the  C.I.E'.  x  ,y  j.  system  where  y  represents  luminance.  See 
"Fundamentals  of  Digital  Image  Processing,"  by  Anil  K.  Jain  (Prentice  Hall,  NJ,  1989;  p  67). 

blendjh,  g.region,  r. colors,  r.combine,  r infer,  rjnask,  r.weight 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 


286 


GRASS  4.0  (Summer  1991) 


U.S.  Anny  CliRL 


r.mask 


GRASS  Reference  Manual 


r.mask 


NAME 

r.mask  -  Hstablishes  or  removes  the  current  working  mask. 

(GRASS  Raster  Program) 

SYNOPSIS 

ran ask 

DESCRIPTION 

The  r.mask  program  allows  the  user  to  block  out  certain  areas  of  a  map  from  analysis,  by  "hiding’' 
them  from  sight  of  other  GRASS  programs.  This  is  done  by  establishing  a  mask.  While  a  mask  exists, 
most  GRASS  programs  will  operate  only  on  data  falling  inside  the  masked  area,  and  ignore  any  data 
falling  outside  of  the  mask. 

Because  the  mask  is  actually  only  a  reclass  file  called  "MASK"  that  is  created  when  the  user  identifies 
a  mask  using  r.mask ,  it  can  be  copied,  renamed,  removed,  and  used  in  analyses,  just  like  other  GRASS 
raster  map  layers,  lhe  user  should  be  aware  that  a  mask  remains  in  place  until  a  user  renames  it  to 
something  other  than  "MASK",  or  removes  it  using  r  jnask  or  g. remove. 

r.mask  provides  the  following  options: 

1  Remove  the  current  mask 

2  Identify  a  new  mask 
kl-TURN  lixit  from  program 

lhe  user  establishes  a  new  mask  by  choosing  option  (2).  The  user  will  be  asked  to  name  an  existing 
raster  map  layer  from  among  those  available  in  the  current  mapset  search  path.  Once  done,  the  user  is 
shown  a  listing  of  this  map’s  categories,  and  is  asked  to  assign  a  value  of  "1"  or  "0”  to  each  map 
category.  /Verts  assigned  category  value  T"  will  become  part  of  the  mask’s  surface,  while  areas 
assigned  category  value  "0"  will  become  "no  data"  areas  in  the  MASK  file. 

If  a  category  is  not  assigned  category  value  "1"  it  will  automatically  be  assigned  the  category  value  ”0" 
in  the  resulting  MASK  file.  Any  cells  falling  in  category  "0"  will  fall  outside  the  newly  formed  mask, 
;uk!  their  jiresence  w  ill  lx:  ignored  by  GRASS  programs  run  later  on,  as  long  as  the  MASK  file  rema  l 
in  place. 

NOTES 

lhe  above  metluxl  for  specifying  a  "mask"  may  seem  counterintuitive.  Aeas  inside  the  mask  are  not 
hidden;  areas  cxitside  the  mask  will  lx:  ignored  until  the  MASK  file  is  removed. 

Ibis  program  actually  creates  a  raster  map  layer  (reclass  type)  called  MASK ,  which  can  be 
manipulated  (renamed,  removed,  copied,  etc.)  like  any  other  raster  map  layer. 

Somewhat  similar  program  functions  to  those  performed  by  r.mask  can  be  done  using  r.mapcalc , 
g. region,  and  other  (Tognuns. 

This  program  c;ut  only  lx:  run  interactively. 

SEE  ALSO 

copy,  g. region,  g.remove,  g.rename,  r.combine,  r.infer,  r.mapcalc,  r.mapmask,  r.reclass, 
r.w  eight 

AUTHOR 

Michael  Shapiro,  U  S.  Army  (  nnstmetion  1-nginccring  Research  Uilxvratory 


GRASS  4.0  (Summer  l‘>‘)|) 


US.  Anm  (T.RI 


287 


r.mlilter 


GRASS  R<  .  ence  Manual 


r.mfilter 


NAME 

r.nfilter  -  Raster  file  matrix  filter. 

(GRASS  Raster  Program) 

SYNOPSIS 

ramfilter 
ran  filter  help 

r  jnfilter  [-qpz]  input  -name  ou;  „=name  filter  =name  [repeat  rvalue]  [  title  =”phrase"\ 
DESCRIPTION 

r.mfilter  filters  the  raster  input  to  produce  the  raster  output  according  to  the  matrix  filter  designed  by 
the  user  (see  FILTERS  below).  The  filter  is  applied  repeat  times  (default  value  is  1).  The  output 
raster  map  layer  can  be  given  a  title  if  desired.  (This  title  should  be  put  in  quotes  if  it  contains  more 
than  one  word.) 

OPTIONS 

The  program  can  be  run  either  non-interactively  or  interactively.  To  run  rjnfUter  non-interactively ,  the 
user  should  specify  desired  flag  settings  and  parameter  values  or  the  command  line,  using  the  form: 

ran  filter  [-qpz]  input  -name  output  --name  filter  ^name  [repeat  =value\  [title  =''phrase"] 

If  the  user  specifies  input,  output,  and  filter  file  names  on  the  commaH  line,  other  parameters  whose 
values  are  unspecified  on  the  command  line  will  be  set  to  their  default  values  (see  below). 


Alternately,  the  user  can  simply  type  ran  filter  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  flag  settings  and  parameter  values  using  the  standard  GRASS 
parser  interface  described  in  the  manual  entry  for  parser. 

Flags: 

-q  T.mfUter  will  normally  print  messages  to  indicate  what  it  is  doing  as  it  proceeds. 

If  the  user  specifies  the  -q  flag,  the  program  will  run  quietly. 

-z  The  filter  is  applied  only  to  zero  category  values  in  the  input  raster  map  layer. 

The  non-zero  category  values  .ire  not  changed.  Note  that  if  there  is  more  than 
one  filter  step,  this  rule  is  applied  to  the  intennediate  raster  map  layer  -  only  zero 
category  values  which  result  from  the  first  filter  will  be  changed,  hi  nxist  cases 
this  will  NOT  be  the  desired  result.  Hence  -z  should  lie  used  only  with  single 
step  fi Iters. 

Parameters: 


inpot  name 
output  name 
filter  =name 


repea t— value 


title  =”  phrase” 


'I he  name  of  an  existing  raster  file  containing  data  values  to  be  filtered. 

Ihe  name  of  the  new  raster  file  to  contain  filtered  program  output. 

The  name  of  an  existing,  user-created  UNIX  ASCII  file  whose  contents  is  a 
matrix  defining  the  way  in  which  the  input  file  will  lie  filtered.  The  format  of 
this  file  is  described  below,  under  FILTERS. 

Ilie  number  of  times  the  filter  is  to  be  applied  to  the  input  data. 

Options:  integer  values 
litefault:  1 

A  title  to  lie  assigned  to  the  filtered  raster  output  map.  If  the  title  exceeds  one 
word,  it  should  lie  quoted. 

Default:  (none) 
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FILTERS 

The  filter  file  is  a  normal  UNIX  ASCII  file  designed  by  the  user.  It  has  the  following  format: 

TITLE  title 

MATRIX  n 

n  lines  of  n  integers 

DIVISOR  d 

TYPE  S/P 

TITIJE  A  one-line  title  for  the  filter.  If  a  title  was  not  specified  on  the  command  line,  it  can  be 
specified  here.  This  title  would  be  used  to  construct  a  tide  for  the  resulting  raster  map 
layer.  It  should  be  a  one-line  description  of  the  filter. 

MATRIX  The  matrix  (n  x  n)  follows  on  the  next  n  lines,  n  must  be  an  odd  integer  greater  than  or 
equal  to  3.  The  matrix  itself  consists  of  n  rows  of  n  integers.  The  integers  must  be 
separated  from  each  other  by  at  least  1  blank. 

DIVISOR  The  filter  divisor  is  d.  If  not  specified,  the  default  is  1.  If  the  divisor  is  zero  (0),  then  the 
divisor  is  dependent  on  the  category  values  in  the  neighborhood  (see  HOW  THE  FILTER 
WORKS  below). 

TYPE  The  filter  type.  S  means  sequential,  while  P  means  parallel.  If  not  specified,  die  default  is 

S. 

Secjuential  filtering  happens  in  place.  As  the  filter  is  applied  to  the  raster  map  layer,  the 
category  values  that  were  changed  in  neighboring  cells  affect  the  resulting  category  value  of 
the  current  cell  being  filtered. 

Parallel  filtering  happens  in  such  a  way  that  the  original  raster  map  layer  category  values 
arc  used  to  produce  the  new  category  value. 

More  than  one  filter  may  be  specified  in  the  filter  file.  The  additional  filters)  are  described  just  like  the 
first.  For  example,  the  following  describes  two  filters: 

EXAMPLE  FILTER  FILE 

ITU I-  3x3  average,  non- zero  data  only,  followed  liy  5x5  average 

MATRIX  3 

1  1  1 
1  1  1 
1  1  I 

DIVISOR  0 

IYPE  P 

MAIRIX  5 

1  I  1  1  1 
11111 
1  I  I  1  1 
1  I  1  1  1 
I  1  I  1  1 
DIVISOR  25 

IYPI  I’ 


2  S>  i 
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HOW  THE  FILTER  WORKS 

The  filter  process  produces  a  new  category  value  for  each  cell  in  the  input  raster  map  layer  by 
multiplying  the  category  values  of  the  cells  in  the  n  x  n  neighbothood  around  the  center  cell  by  the 
corresponding  matrix  value  and  adding  tl^m  together.  If  a  divisor  is  specified,  the  sum  is  divided  by 
this  divisor,  rounding  to  the  nearest  integer.  (If  a  zero  divisor  was  specified,  then  the  divisor  is 
computed  for  each  cell  as  the  sum  of  the  MATRIX  values  where  the  corresponding  input  cell  is  non¬ 
zero.) 

If  more  than  one  filter  step  is  specified,  either  because  the  repeat  value  was  greater  than  one  or  because 
the  filter  file  contained  more  than  one  matrix,  these  steps  are  performed  sequentially.  This  means  that 
first  one  filter  is  applied  to  file  entire  input  raster  map  layer  to  produce  an  intermediate  result;  then  the 
next  filter  is  applied  to  the  intermediate  result  to  produce  another  intermediate  result;  and  so  on,  until 
the  final  filter  is  applied.  Then  the  output  cel!  is  written. 

NOTES 

If  the  resolution  of  the  geographic  region  does  not  agree  with  the  resolution  of  the  raster  map  layer, 
unintended  resampling  of  the  original  data  may  occur.  The  user  should  be  sure  that  the  geographic 
region  is  set  properly. 

SEE  ALSO 

g.region,  r.clump,  rjieighbors,  and  parser 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Tngineering  laboratory 
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NAMK 

r. neighbors  -  M;ikes  each  cell  category'  value  a  function  of  the  category  values  assigned  to  the  cells 
around  it.  and  stores  new  cell  values  in  an  output  raster  map  layer. 

(GRASS  Rosier  Program) 

SYNOPSIS 

r  .neighbors 
rjieighbors  help 

rjieighbors  [-aq]  input  name  output  --name  method  name  siz  e=value  [title  ="phrase'"} 
DESCRIPTION 

r.neighbors  looks  at  each  cell  in  a  raster  input  file,  and  examines  the  category  values  assigned  to  the 
cells  in  sonic  user  defined  "neighborhood'  around  it.  It  outputs  a  new  raster  map  layer  in  which  each 
cell  is  assigned  a  category  value  that  is  some  (user- specified)  function  of  the  values  in  that  cell’s 
neighborhood.  1  or  example,  each  cell  in  the  output  layer  might  be  assigned  a  category  value  equal  to 
the  avenge  of  tlx-  category  values  appearing  in  its  3  x  3  cell  "neighborhood"  in  the  input  layer. 

The  program  will  be  run  non- interactively  if  the  user  specifies  program  arguments  (see  OPITONS)  on 
the  command  line.  Alternately,  the  user  can  simply  type  rjieighbors  on  the  command  line,  without 
program  arguments.  In  this  case,  the  user  will  he  prompted  for  flag  settings  and  parameter  values. 

OPTIONS 

The  user  mast  specify  the  names  of  the  raster  map  layers  to  be  used  for  input  and  output,  the  method 
used  to  analyze  neighbor+Kxxi  category  values  (i.e.,  the  neighborhood  function  or  operation  to  be 
performed),  and  the  size  of  the  neighborhrxxi  Optionally,  the  user  can  also  specify  the  title  to  be 
assigned  to  the  raster  map  layer  output,  elect  to  not  align  the  resolution  of  the  output  with  that  of  the 
input  (tlx-  -a  iptinn),  and  elect  to  run  rjieighbors  quietly  (the  -q  option).  These  options  are  described 
further  below. 

Neighborhood  Operation  Methtxis:  The  neighborhood  eperators  determine  what  new  category  value 
a  center  cell  in  a  neighlxrrhcxxl  will  have  after  examining  category  values  inside  its  neighboring  cells, 
bach  cell  in  a  raster  n  ap  layer  becomes  the  center  cell  of  a  neighborhood  as  the  neighborhood  window 
moves  from  cell  to  cell  throughout  the  map  layer.  r.neighbors  can  perform  the  following  operations: 

average 


median 

mode 

minimum 

maximum 


diversity 
inter ‘per  si  on 


( iKASS  -J  0  (Sumiixi  l‘,lM 


The  average  category  value  within  the  neighlxrrlxxxi.  In  the  following  example, 
the  result  would  be: 

(7,4  +  6  +  5  +  4.3)/?  =  5.66 

The  result  is  rouixled  to  the  nearest  integer  (in  this  case  6). 

lhe  category  value  found  half-way  through  a  list  of  the  neighborhood's  category 
values,  when  these  are  ranged  in  numerical  order. 

The  most  frequently  occurring  category  value  in  the  neighbortxxxl. 

lhe  minimum  category  value  within  the  neighlxrrlxxxi. 

The  maximum  category  value  w  ithin  the  neighborhood. 


Raw  ITit  a 

Qx-rat  ion 

New  Ihta 

7  1  7 

_ i  _ 

1  5 

1 

|  | 

1 

4  |  7 

I  . . . 

!  4 

- >| 

|  6  | 

.  .1 _ l  . 

7  |  6 

1 

1  4 

1 

1  1 

1  1 

I  I- 

The  iximbcr  of  different  category  values  within  the  neighlxvrtxxxl  In  the  above 
example,  the  diversity  is  four. 

lhe  percentage  of  cells  containing  categories  which  differ  fn'in  the  category 

1:  S  Anmil  .Rl  .’<H 
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assigned  to  the  center  cell  in  the  neighborhood,  plus  1 .  In  the  above  example,  the 
interspersion  is: 

5/8  .  100  +  1  =  633 

The  result  is  rounded  to  the  nearest  integer  (in  this  case  64). 

Neighborhood  Size:  The  neighborhood  size  specifies  which  cells  surrounding  any  given  cell  fall  into 
the  neighborhood  for  that  cell.  The  size  must  be  an  odd  integer.  Options  are:  1,  3,  5,  7,  9, 11, 13,  15, 
17,  19,  21,  23,  and  25.  For  example, 

L\~-U 

3x3  neighborhood  --->  |_|_|_| 


-a  If  specified,  rjieighbors  will  not  align  the  output  raster  map  layer  with  that  of  the  input  taster 
map  layer.  The  rjieighbors  program  works  in  the  current  geographic  region.  It  is 
recommended,  but  not  required,  that  the  resolution  of  the  geographic  region  be  the  same  as  that 
of  the  raster  map  layer.  By  default,  if  unspecified,  rjieighbors  will  align  these  geographic 
region  settings. 

-q  If  specified,  rjieighbors  will  run  relatively  quietly  (i.e.,  without  printing  to  standard  output 
notes  on  the  program's  progress).  If  unsjpecified,  the  program  will  paint  messages  to  standard 
output  by  default. 

NOTES 

The  rjieighbors  program  works  in  the  current  geographic  region  with  the  current  mask,  if  any.  It  is 
recommended,  but  not  required,  that  the  resolution  of  the  geographic  region  be  the  same  as  that  of  the 
taster  map  layer.  By  default,  rjieighbors  will  align  these  geographic  region  settings.  However,  the 
user  can  elect  to  keep  original  input  and  output  resolutions  which  are  not  aligned  by  specifying  this 
(eg.,  using  the  -a  option). 

r. neighbors  copies  the  GRASS  color  files  associated  with  the  inprut  raster  map  layer  for  those  output 
map  layers  that  are  based  on  the  neighborhood  average,  median,  mode,  minimum,  and  maximum. 
Because  diversity  and  interspxrsion  are  indices,  rather  than  direct  correspxmdents  to  input  category 
values,  no  color  files  are  copied  for  these  map  layers.  (The  user  should  note  that  although  the  color 
file  is  copried  for  averaged  neighborhood  function  output,  whether  or  not  the  color  file  makes  sense  for 
die  output  will  be  dependent  on  the  input  data  values.) 

SEE  ALSO 

g.region,  r. clump,  rjnapcalc,  rjnask,  rjnfUter,  r. support 

AUTHOR 

Michael  Shapriro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.outMstii  -  Converts  a  raster  map  layer  into  an  ASCII  text  file. 

(GRASS  Raster  Data  Export  Program) 

SYNOPSIS 

r^ntjudi 
rjwtjucii  help 

r.out-ascii  [-b]  map  =name  [digits  =value] 

DESCRIPTION 

r.out.ascii  converts  a  user-specified  raster  map  layer  (map=na/ne)  into  an  ASCH  text  file  suitable  for 
export  to  other  computer  systems.  The  digits=va/ue  option  (where  value  is  a  number  erf  the  user’s 
choice)  can  be  used  to  request  that  numbers  in  the  ouput  be  equally-spaced  (i.e.,  columnar  output). 
Each  category  value  in  the  ASCII  map  layer  will  then  take  up  value  number  of  spaces.  However,  to 
use  this,  the  user  should  know  the  maximum  number  of  digits  that  will  occur  in  the  output  file,  and  add 
one  to  this  number  (to  leave  a  space  between  each  column).  The  user  can  find  the  maximum  number 
of  digits  occurring  in  the  output  file  by  running  r.out.ascii  without  the  digits=vaiue  option. 

The  GRASS  program  r. in. ascii  can  be  used  to  perform  the  reverse  function,  converting  an  ASCII  file 
in  suitable  format  to  GRASS  raster  file  format. 

Flag: 

-h  Suppress  printing  of  header  information. 

Parameters: 

map  name  Name  of  an  existing  raster  map  layer. 

digits  =v<i/ue  The  minimum  number  of  digits  (per  cell)  to  be  printed. 

r.out.ascii  can  lie  run  either  norvinteractively  or  interactively.  The  program  will  be  run  norv 
interactivelv  if  the  user  specifies  the  name  of  a  raster  map  layer  and  (optionally)  a  value  for  digits, 
using  the  form 

r.out.ascii  map  name  [digits=va/ue] 

where  name  is  the  name  of  a  raster  map  layer  to  be  converted  to  ASCII  format,  and  value  is  the 
minimum  number  of  digits  (per  cell)  to  lx  printed  to  output.  The  user  can  also  specify  the  -h  option  to 
suppress  the  output  of  file  header  information. 

Alternately,  the  user  can  simply  type  r .out-ascii  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  parameter  values  using  the  standard  GRASS  parser  interface 
described  in  the  mutual  entry  for  parser. 

NOTES 

Ihe  output  from  r.out.ascii  may  Ire  placed  into  a  file  by  using  the  UNIX  redirection  mechanism;  eg.: 

r.out-ascii  map  soils  >  out. file 

Ihe  rxitput  file  out.file  can  then  Ire  printed  or  copied  onto  a  magnetic  tape  or  floppy  disk  for  export 
pur|x>scs. 

SEE  ALSO 

r.in.ascii,  ;uid  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Construction  Engineering  Research  laboratory 
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NAME 

r.patch  -  Creates  a  composite  raster  map  layer  by  using  kncwn  category  values  from  one  (or  more) 
map  layers)  to  fill  in  areas  of  "no  data"  in  another  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

r  .patch 
r  .patch  help 

r .patch  [-q]  input =namt'{  /iame,...\  output  name 
DESCRIPTION 

The  GRASS  program  r.patch  allows  the  user  to  assign  known  data  values  from  other  raster  map  layers 
to  the  " no  data "  areas  (those  assigned  category  value  0)  in  another  raster  map  layer.  This  program  is 
useful  for  making  a  composite  raster  map  layer  from  two  or  more  adjacent  map  layers,  for  filling  in 
"holes"  in  a  raster  map  layer’s  data  (eg.,  in  digital  elevation  data),  or  for  updating  an  older  map  layer 
with  more  recent  data. 

The  program  will  be  run  non- interactively  if  the  user  specifics  program  arguments  on  the  command 
line,  using  the  form 

r .patch  [-q]  input  ^name[pame,...)  output  =name 

where  each  input  name  is  the  name  of  a  raster  map  layer  to  be  patched,  the  output  name  is  the  name 
assigned  to  the  new  composite  raster  map  layer  containing  the  patched  result,  and  the  (optional)  -q  flag 
directs  r.patch  to  run  quietly. 

The  first  name  listed  in  the  string  input  ^name, name, name,  ...  is  the  name  of  the  base  map  whose 
zero  data  values  will  be  attempted  to  be  filled  by  non-zero  data  values  in  the  second  through  tenth  input 
name  maps  listed.  The  second  through  tenth  input  name  maps  wtll  be  used  to  supply  remaining 
missing  (zero)  data  values  for  the  first  input  map  name ,  based  on  the  or*’<er  in  which  they  are  listed  in 
the  string  input  =name, name, name,  .... 

Alternately,  the  user  can  simply  type  r .patch  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  the  flag  setting  and  parameter  values  using  the  standard  GRASS 
parser  interface  described  in  the  manual  entry  for  parser. 

Flag: 

-q  Directs  that  r.patch  run  quietly,  suppressing  output  of  messages  on  program 

progress  to  standard  output. 

Parameters: 


input  =name,name,... 

The  name(s)  of  between  one  and  ten  existing  raster  map  layers  to  be  patched 
together.  The  first  of  tire  ten  maps  listed  will  be  used  as  a  Ira  sc  map,  and  the 
second  through  tenth  mips  listed  will  be  used  to  supply  missing  (zero)  category 
values  for  the  first  map. 

output  =name  The  name  of  the  new  raster  map  to  contain  the  resultant  patclied  output. 


EXAMPLE 

Below,  the  raster  map  layer  on  the  far  left  is  patched  with  the  middle  (patching )  raster  map  layer,  to 
produce  the  composite  raster  map  layer  on  the  right. 


11102200 
1 1 022200 
33332200 
33330000 
33300000 
00000000 


0  0  l  1  0  0  0  0 
00110000 
00000000 
44444444 
44444444 
44444444 


11112200 

11122200 

33332200 

33334444 

33344444 

44444444 
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Switching  the  patched  and  the  patching  raster  map  layers  produces  the  following  results: 


00110000 

00110000 

00000000 

44444444 

44444444 

44444444 


11102200 

11022200 

33332200 

33330000 

33300000 

00000000 


11112200 

11112200 

33332200 

44444444 

44444444 

44444444 


NOTES 

Frequently,  this  program  is  used  to  patch  together  adjacent  map  layers  which  have  been  digitized 
separately.  The  (nograms  v.mkquads  and  vjnkgrid  can  be  used  to  make  adjacent  maps  align  neatly. 


The  user  should  check  the  current  geographic  region  settings  before  running  r.patch,  to  ensure  that  the 
region  boundaries  encompass  all  of  the  data  desired  to  be  included  in  the  composite  map. 

Use  of  r.patch  is  generally  followed  by  use  of  the  GRASS  programs  g.remove  and  g.rename; 
g.remove  is  used  to  remove  the  original  (un- patched)  raster  map  layers,  while  g.rename  is  used  to  then 
assign  to  the  newly- created  composite  (patched)  raster  map  layer  the  name  of  the  original  raster  map 

layer. 


r.patch  creates  support  files  for  the  patched,  composite  output  map. 

SEE  ALSO 

g.region,  g.remove,  g.rename,  rjnapcalc,  r. support,  v.mkgrid,  v.mkquads,  and  parser 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.poly  -  Extracts  area  edges  from  a  raster  map  layer  and  converts  data  to  GRASS  vector  format. 
(GRASS  Raster  Program) 

SYNOPSIS 

r-poiy 

r.poly  help 

r.poiy  [4]  input  name  output  =name 
DESCRIPTION 

r.poly  scans  the  named  input  raster  map  layer,  extracts  area  edge  features  from  it,  converts  data  to 
GRASS  vector  format,  and  smoothes  vectors. 

r.poly  first  traces  the  perimeter  of  each  unique  area  in  the  raster  map  layer  and  creates  vector  data  to 
represent  it.  The  cell  category  values  for  the  raster  map  layer  will  be  used  to  create  attribute 
information  for  the  resultant  vector  area  edge  data. 

A  tme  vector  tracing  of  the  area  edges  might  appear  blocky,  since  the  vectors  outline  the  edges  of 
raster  data  that  are  stored  in  rectangular  cells.  To  produce  a  better-looking  vector  map,  r.poly 
smoothes  the  comers  of  the  vector  data  as  they  are  being  extracted.  At  each  change  in  direction  (i.e., 
each  comer),  the  two  midpoints  of  the  comer  cell  (half  the  cell’s  height  and  width)  are  taken,  and  the 
line  segment  connecting  them  is  used  to  outline  this  comer  in  the  resultant  vector  file.  (The  cell’s 
comennost  node  is  ignored.)  Because  vectors  are  smoothed  by  this  program,  the  resulting  vector  map 
will  not  be  "true"  to  the  raster  map  from  which  it  was  created.  The  user  should  check  the  resolution  of 
tire  geographic  region  (and  the  original  data)  to  estimate  the  possible  error  introduced  by  smoothing. 

OPTIONS 

'I he  user  can  nin  this  program  either  non-interactively  or  interactively,  'lire  program  will  be  run  non 
interactively  if  the  user  specifies  program  arguments  and  Hag  settings  on  the  command  line,  using: 

r.poly  [4]  input  name  output  name 

Alternately,  the  user  can  simply  type  r.poly  on  the  command  line  without  prog  nun  arguments.  In  this 
case,  the  user  will  be  prompted  for  parameter  values  and  flag  settings  using  the  standard  GRASS  parser 
interface  described  in  the  manual  entry  for  parser. 

Flag: 

-I  Smooth  comers. 

Parameters: 

input  =name  Use  the  existing  raster  map  name  as  input, 

output =*uune  Set  the  new  vector  output  file  name  to  name. 

NOTES 

r.poly  extracts  only  ;uea  edges  from  the  named  raster  input  file.  If  the  raster  file  contains  other  data 
(i.e.,  line  edges,  or  point  data),  the  output  may  be  wrong. 

Ihe  user  must  nin  v. support  on  the  resultiuit  file  to  build  the  needed  topology  infonnation  stored  in  the 
dig_plus  file. 

SEE  ALSO 

v. sup  port  and  parser 

AUTHORS 

Original  version  of  r.poly: 

Jean  1V.cU,  U.S.  Army  Onstniclion  Engineering  Research  laboratory 

Andrew  Hcckin,  U.S.  Army  Constmction  Engineering  Research  I  alxrratory 

Modified  program  for  smoothed  lines:  David  Salnik,  Central  Washington  University.  WA 
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NAME 

r.profile  -  Outputs  the  raster  map  layer  values  lying  on  user-defined  line(s). 

(GRASS  Raster  Program) 

SYNOPSIS 

r^profile 
r .profile  help 

r .profile  map  =name  [result  type]  [width rvalue] 

\\ne=east, north, east, north[,east,north,east, north,. 

DESCRIPTION 

This  program  outputs,  in  ASCII,  the  values  assigned  to  those  cells  in  a  raster  map  layer  that  lie  along 
one  or  more  lines  ("profiles").  The  lines  are  described  by  their  starting  and  ending  coordinates.  The 
profiles  may  be  single-cell  wide  lines,  or  multiple- cell  wide  lines.  The  output,  for  each  profile,  may  be 
the  category  values  assigned  to  each  of  the  cells,  or  a  single  aggregate  value  (eg.,  average  or  median 
value). 

COMMAND  LINE  OPTIONS 
Parameters: 

map  name  Raster  map  to  be  queried. 

result  =fype  Type  erf  result  to  be  output. 

Options:  raw,  median,  average 
Default:  raw 

Raw  results  output  each  of  the  category  values  assigned  to  all  cells  along  the 
profile.  Median  and  average  output  a  single  value  per  profile:  average  outputs  the 
average  category  value  erf  all  cells  under  the  profile;  median  outputs  the  median 
cell  category  value. 

\\M=easi,north,east,norih[,east,northJeast, north,...] 

The  geographic  coordinates  of  the  starting  and  ending  points  that  define  each 
profile  line,  given  as  easting  and  northing  coordinate  pairs.  The  user  must  stal  : 
the  starting  and  ending  coordinates  of  at  least  one  line,  and  may  optionally 
include  starting  and  ending  coordinates  of  additional  lines. 

width  =value  Profile  width,  in  cells  (odd  number). 

Default:  1 

Wider  profiles  can  be  specified  by  setting  the  width  to  3,  5,  7,  etc.  The  profiles 
are  then  formed  as  rectangles  3,  5,  7,  etc.,  cells  wide. 

OUTPUT  FORMAT 

Ihe  txitpiu  from  this  command  is  printed  to  the  standard  output  in  ASCII.  The  fonnat  of  the  output 
varies  slightly  depending  on  the  type  of  result.  The  first  number  printed  is  the  number  of  cells 
associated  with  the  profile.  For  raw  'Hit put,  this  number  is  followed  by  the  individual  cell  values.  For 
average  and  median  <xit|xil,  this  number  is  followed  by  a  single  value  (i.e.,  the  average  or  tlie  median 

value). 

Ihesc  examples  are  for  the  elevation.dem  raster  map  layer  in  the  spearfish  sample  data  set  distributed 
with  ( iRASS  4.0: 

Single  cell  profile: 

r.profile  map  elevation.dem  line=593655y4917280,593726,4917351 

4  1540  1551  I  .''57  1550 
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3-cell  wide  profile: 

r .profile  map=devalionu)e»  line  =593655,49 17280 ,593726 ,4917351  width  =3 

22  1556  1538  1525  1570  1555  1540  1528  1578  1565  1551  1536  1523  1569  1557  1546  1533 
1559  1550  1542  1552  1543  1548 

(Qitput  appears  as  multiple  lines  here,  but  is  really  one  line) 

3-cell  wide  profile  average: 

r .profile  map=elevatian.dem  lint  593655,4917280,593726,4917351  width  3 

result  average 

22  1548.363636 

3-cell  wide  profile  median: 

r .profile  map  elevatiou.dem  line  593655,4917280,593726,4917351  width  =3 

result -  median 

22  1549.000000 

SEE  ALSO 

d.profUe,  r. transect 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

r.random  -  Creates  a  raster  map  layer  and  site  list  file  containing  randomly  located  sites. 

( GRASS  Raster  Program) 

SYNOPSIS 

rjnuidom 
r .random  help 

r .random  [-qzj  input  =name  nsites=numfier[%  ]  [raster  output  name)  (sites^output  =name] 
DESCRIPTION 

The  program  r.random  allows  the  user  to  create  a  raster  map  layer  and  a  site  list  file  containing 
geographic  coordinates  of  points  whose  locations  have  been  randomly  determined.  The  program  locates 
these  randomly-generated  sites  within  the  current  geographic  region  and  mask  (if  any),  on  non-zero 
category  value  data  areas  within  a  user-specified  raster  map  layer.  If  the  user  sets  the  -z  flag,  sites  will 
be  randomly  generated  across  all  cells  (even  those  assigned  category  value  0). 

The  raster _output  raster  map  layer  is  created  in  the  users  current  mapset.  The  category  values  and 
corresponding  category  names  already'  associated  with  the  random  site  locations  in  the  input  map  layer 
are  assigned  to  these  sites  in  the  raster_output  map  layer.  A  color  table,  designed  to  contrast  with  that 
assigned  to  the  input,  is  generated  for  the  raster _output. 

The  sitejists  file  created  by  r.random  contains  a  listing  of  the  sites’  geographic  coordinates;  these 
coordinates  are  the  center  points  of  the  randomly -selected  cells. 

OPTIONS 

The  user  may  specify  the  quantity  of  random  fixations  to  be  generated  either  as  a  positive  integer 
(eg.,  10),  or  as  a  percentage  of  the  raster  map  layer’s  total  area  (eg.,  10%,  or  3.05%).  If 
unspecified,  the  number  of  sites  is  set  to  ’0’  by  default.  If  stated  as  a  percentage  of  the  raster  map’s 
total  size,  the  number  of  random  fixations  generated  w  ill  lx  set  equal  to  the  number  of  cells  contained 
within  the  stated  percentage  of  the  raster  map  layer.  Options  are  0-100;  percentages  less  than  one 
percent  may  be  stated  as  decimals.  The  default  percentage  value  used,  if  unspecified  by  the  user,  is  ’0’ 
(Note  that  choosing  1%  of  a  raster  map’s  cells  frequently  produces  an  alxindance  of  random  locations.) 

r.random  can  lx  nm  interactively  or  non  interactively.  The  user  may  provide  program  arguments  on 
the  command  line,  specifying  an  input  map  layer  name  (input  =name),  output  raster  map  layer  name 
(raster_output=7ia/ne).  output  site  list  file  name  (sites_output=/iamr),  and  (optionally)  give  the  number 
of  sites  to  lx  randomly  generated  as  a  total  number  of  sites  (nsites ^number)  or  as  a  percentage  of  the 
imp’s  size  (nsites ~numher%).  The  user  can  also  direct  that  r.random  run  quietly  (using  the  -q) 
option,  and/or  direct  r.random  to  also)  generate  random  site  fixations  against  cells  containing  category 
zero  (using  the  -z  option). 

Alternately,  the  user  can  simply  type  r .random  on  the  command  line  without  program  arguments.  In 
this  case,  the  user  will  lx  prompter!  tor  txeoled  inputs  anoi  option  choices  using  tlx  standard  GRASS 
user  interface  described  in  tlx  manual  entry  fox  parser. 

Flags; 

-q  Riui  quietly,  r.random  will  normally  print  output  nxssages  to  standard  output  as 

it  mils.  Tlx  o|  option  w  ill  suppress  the  printing  of  these  messages. 

Incluok-  .mas  assigixol  a  category  value  of  zero  within  the  pool  o>f  areas  within 
which  r.random  will  raixloimlv  generate  site  fixations  If  the  /  option  is 
s|xcifiool.  sites  that  fail  in  aromas  assigneol  a  category  value  of  zero  in  tlx  input 
map  layer  will  lx-  assigixol  to  a  now  ly-created  category  in  the  oxitpui  rasici  map 
lay  er.  If  tlx  z  llag  is  not  set,  cells  hav  ing  category  value  zero  in  tile  oxiijxu  lav  o  r 
will  roproso-nt  tlx  areas  at  which  raiulomly  loxateol  sites  were  non  placool 
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Parameters: 

fnpo t=name  An  existing  raster  map  layer  in  the  user’s  current  mapset  search  path,  r.random 

will  randomly  generate  sites  on  a  user-specified  portion  of  the  cells  in  this  input 
raster  map. 

□sites  =number  or  nutts=number% 

Allows  the  user  to  specif)  the  quantity  of  sites  to  lie  randomly  generated  as  either 
a  positive  integer ,  or  as  a  percentage  value  of  the  number  of  cells  in  the  input 
map  layer.  If  stated  as  a  positive  integer,  number  is  the  number  of  sites  (i.e.. 
number  of  cells)  to  appear  in  the  raster_output  layer  and/or  sites^  output  file. 
Options:  Non-percentage  values  should  be  given  as  positive  integer  values  less 
than  or  equal  to  the  number  of  cells  in  the  input  map  layer.  Percentage  values 
given  should  be  within  the  range  0.00  -  100.00  (decimal  values  are  allowed). 

raster.output  ^mame 

Ihe  new  raster  map  layer  to  hold  program  output.  Ihis  map  will  contain  the  sites 
randomly  generated  by  r.random.  If  the  z  flag  is  not  set,  till  sites  will  be 
assigned  whatever  category  values  were  assigned  these  cell  locations  in  the  input 
raster  map  layer.  If  the  -z  flag  is  set,  all  sites  except  those  falling  on  cells 
assigned  category  value  0  in  the  input  value  will  be  assigned  the  category  values 
assigned  these  cells  in  the  input  layer;  sites  falling  on  cells  assigned  category 
value  0  in  the  input  layer  will  be  assigned  to  a  newly  created  category  in  the 
raster_output  layer. 

sites,  output  —Jiame  Ihe  new  GRASS  sitejists  tile  to  hold  program  output.  If  no  sites  ^output  file 
name  is  given  on  the  command  line,  no  sitejists  tile  will  lie  created  by 
r.random.  (See  raster_output  parameter  description,  alxive.) 

Note.  Although  the  user  need  not  request  that  r.random  output  both  a  raster  map 
layer  {raster ^output)  and  a  site  list  file  (sites ^output),  the  user  must  specify  that 
at  least  one  of  these  outputs  lie  produced. 

NOTES 

To  create  random  site  locations  within  some,  but  not  all.  nonzero  categories  of  the  input  raster  map 

layer,  the  user  must  first  create  a  reclassified  raster  map  layer  of  the  original  raster  map  layer  (e.g.. 

using  the  GRASS  program  r.reclass)  that  contains  only  the  desired  categories,  and  then  use  the 

reclassed  raster  map  layer  as  input  to  r.random. 

SEE  ALSO 

g.region,  r.mask,  r.reclass,  and  parser 

AUTHOR 

I>.  James  Ifinthome,  GIS  laboratory,  Central  Washington  University 
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NAME 

r.reclass  -  Creates  a  new  map  layer  whose  category  values  are  based  upon  the  user’s  reclassification  of 
categories  in  an  existing  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

rj-eclass 
r  j- eel  ass  help 

r .reclass  input^/uvne  output  name  [title  name] 

DESCRIPTION 

r.redass  creates  an  output  map  layer  based  on  an  input  raster  map  layer.  The  output  map  layer  will 
be  a  reclassification  of  the  input  map  layer  based  on  reclass  rules  input  to  r.reclass,  and  can  be  treated 
in  much  the  same  way  that  raster  Ivies  are  treated.  A  title  for  the  output  map  layer  may  be  (optionally) 
specified  by  the  user. 

The  reclass  rules  are  read  from  standard  input  (i.e.,  from  the  keyboard,  redirected  from  a  file,  or  piped 
through  another  progiairi) 

The  jvrogram  will  be  run  non- interactively  if  the  user  specifies  the  name  of  the  raster  map  layer  to  be 
reclassified,  the  name  of  an  output  layer  to  hold  reclass  rules,  and  (optionally)  the  name  of  a  title  for 
the  output  map: 

rj- eel  ass  input  name  output  =name  [title  =name] 

After  the  user  types  in  the  above  information  on  the  command  line,  the  program  will  (silently)  prompt 
the  user  for  reclass  niles  to  be  applied  to  the  input  map  layer  categories.  I  he  form  of  these  rules  is 
described  in  further  detail  in  the  sections  on  non- interactive  program  use  reclass  rules  and  examples, 
below. 

Alternately,  the  user  can  simply  type  r.redass  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  all  needed  inputs. 

Before  using  r.redass  one  must  know  the  following: 

1  Ihe  new'  categories  desired;  and,  which  old  categories  fit  into  which  new  categories. 

2  lire  names  of  the  new  categories. 

INTERACTIVE  PROCRAM  USE:  EXAMPLE 

Suppose  we  want  to  reclassify  the  raster  map  layer  roads,  consisting  of  five  categories,  into  the  three 
new  categories:  paved  roads,  unpaved  roads,  and  railroad  tracks.  The  user  is  asked  whether  the  reclass 
table  is  to  lie  established  with  each  category  value  initially  set  to  0,  or  with  each  category  value  initially 
set  to  its  own  value.  A  screen  like  that  shown  below  then  appears,  listing  the  categories  of  the  roads 
raster  map  layer  to  be  reclassified  and  prompting  the  user  for  the  new'  category  values  to  be  assigned 
them. 
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ENTER  NEW  CATEGORY  NUMBERS  FOR  THESE  CATEGORIES 


OLD  CATEGORY  NAME 

OLD 

NEW 

NUM 

NUM 

no  data 

0 

0__ 

Hard  Surface,  2  lanes 

1 

0_ 

Loose  Surface,  1  lane 

2 

0_ 

Improved  Dirt 

3 

0_ 

Unimproved  Dirt  Trail 

4 

0__ 

Railroad,  single  track 

5 

0_ 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 

(OR  <Ctrl-C>TO  CANCEL) 


In  the  following  screen  the  new  category  values  have  been  entered  beside  the  appropriate  (id  category 
names.  Cells  assigned  category  values  2,  3,  and  4  in  the  old  raster  map  layer  are  now  assigned  the  new' 
category  value  2  in  the  reclassed  map;  cell  data  formerly  assigned  to  category  value  5  in  the  old  raster 
map  map  are  now  assigned  the  new  category  value  3  in  the  reclassed  map. 


ENTER  NEW  CATEGORY  NUMBERS  FOR  THESE  CATEGORIES 


OLD  CATEGORY  NAME 

OLD 

NUM 

NEW 

NUM 

no  data 

0 

o__ 

Hard  Surface,  2  lanes 

1 

1__ 

Loose  Surface,  1  lane 

2 

2 _ 

Improved  Dirt 

3 

2 _ 

Unimproved  Dirt  Trail 

4 

2 _ 

Railroad,  single  track 

5 

3 _ 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <CtrI-C>TO  CANCEL) 


Htting  the  escape  key  <ESC>  will  bring  up  the  following  screen,  which  prompts  the  user  to  alter  a 
new  title  and  category  label  for  the  newly  reclassed  categories. 
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ENTER  NEW  CATEGORY  NAMES  FOR  THESE  CATEGORIES 


TITLE:  Roads  Reclassified 
CAT 
NUM 
0 
1 
2 
3 


NEW  CATEGORY  NAME 

no  data 
Paved  Roads 
Unpaved  Roads 
Railroad,  single  track 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
fOR  <Ctri-C>TO  CANCEL) 


Based  upon  the  information  supplied  by  the  user  in  the  above  sample  screens,  the  new  output  map, 
supporting  category,  color,  liistory,  and  header  files  are  created. 

NON-INTERACTIVE  PROGRAM  USE:  RECLASS  RULES 

In  non-interactive  program  use,  the  names  of  an  input  map,  output  map,  and  output  map  title  are  given 
on  the  command  line.  However,  the  reclass  rules  are  still  read  from  standard  input  (i.e.,  from  the 
keyboard,  redirected  from  a  file,  or  piped  through  another  program). 

Qlice  the  user  has  specified  an  input  raster  map  layer,  output  map  layer  name,  and  (optionally)  output 
map  layer  title  by  typing 

rxedass  input  name  output  name  [title  name] 

Lach  line  of  input  must  have  the  following  format: 

input  categories  output  category  [label] 

where  the  input  lines  specify  the  category  values  in  the  input  raster  map  layer  to  be  reclassified  to  the 
new  output  _category  category  value.  Specification  of  a  label  to  be  associated  with  the  new  output 
imp  layer  category  is  optional.  If  specified,  it  is  recorded  as  the  category  label  for  the  new  category 
value.  The  equal  sign  =  is  required.  The  input  _category(ies)  may  consist  of  single  category  values  o 
a  range  of  such  values  in  the  format  "low  thru  high."  The  word  "thru"  must  be  present. 

A  line  containing  only  the  word  end  terminates  the  input. 

NON-INTERACTIVE  PROGRAM  USE:  EXAMPLES 

Ihe  following  examples  may  help  clarify  the  reclass  rules. 

1  'Ihis  example  reclassifies  categories  1,3,  and  5  in  the  input  raster  imp  layer  to  category  1  with 
category  label  "poor  quality"  in  the  output  map  layer,  and  reclassifies  input  raster  map  layer 
categories  2,  4,  and  6  to  category  2  with  the  label  "good  quality"  in  the  output  map  layer. 

13  5  =  1  poor  quality 

2  4  6  =  2  good  quality' 

2  This  example  reclassifies  input  raster  map  layer  categories  1  thru  10  to  output  map  layer 
category  1,  input  imp  layer  categories  11  thm  20  to  output  imp  layer  category  2,  and  input 
map  layer  categories  21  thru  30  to  output  map  layer  category  3,  all  without  labels. 

1  thm  10  =  1 

11  thm  20  =  2 

21  thm  30  =  3 

3  Subsequent  rules  override  previous  rnies.  Therefore,  the  below  example  reclassifies  input  raster 
imp  layer  categories  1  thru  19  and  51  thm  100  to  category  1  in  the  output  map  layer,  input 
raster  map  layer  categories  20  thm  24  and  26  thm  50  to  the  output  map  layer  category  2,  and 
input  raster  map  layer  category  25  to  the  output  category'  3. 
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1  thru  100 
20  thru  50 
25 


1  poor  quality 

2  medium  quality 

3  good  quality 


4 


The  previous  example  could  also  have  been  entered  as: 


1  thru  19  51  thru  100 
20  thru  24  26  thru  50 

25 


1  poor  quality 

2  medium  quality 

3  good  quality 


or  as: 


1  thru  19 
51  thru  100 
20  thru  24 
26  thru  50 
25 


1  poor  quality 
1 

•7 

2  medium  quality 

3  good  quality 


The  final  example  was  given  to  show  how  the  labels  are  handled.  If  a  new  category  value  appears  in 
"lore  than  one  rule  (as  is  the  case  with  new  category  values  1  and  2),  the  last  label  which  was  specified 
becomes  the  label  for  that  category.  In  this  case  the  labels  are  assigned  exactly  as  in  the  two  previous 
examples. 

NOTES 

In  fact,  the  r.reclass  program  does  not  generate  any  new  raster  map  layers  (in  the  interests  of  disk 
space  conservation).  Instead,  a  reclass  table  is  stored  which  will  be  used  to  reclassify  the  original 
raster  map  layer  each  time  the  new  (reclassed)  map  name  is  requested.  As  far  as  the  user  (and 
programmer)  is  concerned,  that  raster  map  has  been  created.  Also  note  that  although  the  user  can 
generate  a  r. reclass  map  which  is  based  on  another  r.reclass  map,  the  new  r.reclass  map  map  will  be 
stored  in  GRASS  as  a  reclass  of  the  original  raster  map  on  which  the  first  reclassed  map  was  based. 
Therefore,  while  GRASS  allows  the  user  to  provide  r.reclass  trap  layer  information  which  is  based  on 
an  already  reclassified  map  (for  the  user’s  convenience),  no  r.reclass  map  layer  (i.e.,  reclass  table) 
will  ever  be  stored  as  a  r.reclass  of  a  r  seel  ass. 

To  convert  a  reclass  map  to  a  regular  raster  map  layer,  set  your  geographic  region  settings  to  match  the 
settings  in  the  header  for  the  reclass  map  (an  ASCII  file  found  under  the  cellhd  directory,  or  viewable 
by  running  r support)  and  then  run  r. resample. 

r.mapcalc  can  also  be  used  to  convert  a  rcclass  map  to  a  regular  raster  map  layer: 

rjmapcalc  rastfr  miip  redavs  map 

where  raster _map  is  the  name  to  be  given  to  the  new  raster  map,  and  reclass_rnap  is  an  existing 
reclass  map. 

BEWARE 

Because  r.reclass  generates  a  table  referencing  some  original  raster  map  layer  rather  than  creating 
reclassed  raster  map  layer,  a  r.reclass  map  layer  will  no  longer  be  accessible  if  the  origin;d  raster  map 
layer  upon  which  it  was  based  is  later  removed. 

A  r.reclass  map  is  not  a  tme  raster  map  layer.  Rather,  it  is  a  table  of  reclassification  values  which 
reference  the  input  raster  map  layer.  Therefore,  users  who  wish  to  retain  reclassified  map  layers  must 
also  save  the  original  input  raster  map  layers  from  which  they  were  generated. 

Category  values  that  are  not  explicitly  reclassified  to  a  new  value  by  the  user  are  reclasscd  to  zero. 
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SEE  ALSO 

r.  resample,  r. rescale 

AUTHORS 

Janies  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory 
Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

r. report  -  Reports  statistics  for  raster  map  layers. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxeport 
r .report  help 

rxeport  [  -hmfq]  map  =name[ /tame,...]  [units  =name\/iame,...}}  [pi  =value\  [pw  =value] 

[  output  =name  ] 

DESCRIPTION 

r.report  allows  the  user  to  set  up  a  series  of  report  parameters  to  be  applied  to  a  raster  map  layer,  and 
creates  a  report.  If  invoked  with  command  line  arguments,  the  report  will  print  out  to  the  screen  only. 
However,  output  may  be  redirected  to  a  file  or  another  program  using  the  UNIX  redirection  mechanism. 
If  invoked  without  command  line  arguments,  the  user  is  given  the  option  of  printing  out  each  report 
and/or  saving  output  to  a  file. 

Ihe  program  will  be  nm  non-interactively,  if  the  user  specifies  the  names  of  raster  map  layers  and  any 
desired  options  on  the  command  line,  using  the  form 

rxeport  [-hmfqj  map  =name[ /tame ,...]  [units=name[/iame ,...]]  [pi  =value\  (pw=va/uej 

where  each  map  name  is  the  name  of  a  raster  map  layer  on  which  to  report,  each  unit  name  is  a  unit  of 
measure  in  which  results  are  to  be  reported,  the  pi  value  gives  the  page  length,  the  pw  value  gives  the 
page  width,  and  the  (optional)  flags  -h,  -m,  -/,  and  -q  have  the  meanings  stated  below. 


Flags: 

-h  Suppress  the  print-out  of  page  headers. 

-m  Report  on  zero  values,  because  a  mask  is  being  used. 

-f  Use  formfeeds  between  pages  when  printing  report  output. 

-q  Run  quietly,  without  printing  program  messages  to  standard  output. 

Parameters: 


map  =name,name, . . . 
units=flome 


pi  =value 
pw  -value 
output  =name 


Names  of  raster  map(s)  on  which  to  report. 

Units  of  measure  in  which  results  are  to  be  reported.  These  units  are  based  on 
the  number  of  cells  in  the  user’s  area  of  interest  (i.e.,  cells  within  the  current 
geographic  region  definition,  and  the  current  mask  [if  any]).  These  are 
established  with  the  programs  g.region  and  r.mask,  respectively. 

Options:  Possible  units  of  measurement  are: 
ml  (cover  measured  in  square  miles ) 
me  (cover  measured  in  square  meters) 
k  (cover  measured  in  square  kilometers) 

a  (cover  measured  in  acres) 

b  (cover  measured  in  hectares) 

c  (the  number  of  cells  in  the  area  of  interest) 
p  (the  percent  cover,  excluding  no  data  areas) 

Page  length,  in  lines,  in  which  report  will  be  output. 

Default:  0  (lines) 

Page  width,  in  character,  in  which  report  will  lie  output. 

Default:  79  (characters) 

Ihe  name  of  a  file  to  store  the  report  in.  If  not  specified,  tlie  report  is  printed 
on  the  tenninal  screen. 


GRASS  4.0  (Summer  1991) 


U.S.  Army  CF.RI. 


r.report 


GRASS  Reference  Manual 


r.report 


Alternately,  the  user  can  amply  type  r .report  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  program  flag  settings  and  parameter  values. 

The  report  itself  coasists  of  two  parts,  a  header  section  and  the  main  body  erf  the  report. 

Ihe  header  section  of  the  report  identifies  the  raster  map  layers)  (by  map  layer  name  and  title), 
location,  inapset,  report  date,  and  the  region  of  interest.  The  area  of  interest  is  described  in  two  parts: 
the  user's  current  geographic  region  is  presented,  and  the  mask  is  presented  (if  any  is  used). 

Ihe  main  body  of  the  report  consists  of  from  one  to  three  tables  which  present  the  statistics  for  each 
category  and  the  totals  for  each  unit  column. 

Note  that,  unlike  ratals,  r.report  allows  the  user  to  select  the  specific  units  of  measure  in  which 
statistics  will  be  reported. 

Hollowing  is  the  result  of  a  r. report  run  on  the  raster  map  layer  geology  (located  in  the  Spearfish,  SD 
sample  data  base),  with  the  units  expressed  in  square  miles  and  acres.  Here,  r.report  output  is  directed 
into  the  file  report. file. 

EXAMPLE: 

r  .report  map  geology  units  raile&^Kres  >  report Jile 


RASTER  MAP  CATEGORY  REPORT 

LOCATION:  spearfish 

Fri  Sep  2  09:20:09 

north:  4928000.00  east: 

609000.00 

REGION: 

south:  4914000.00  west: 

590000.00 

res:  100.00  res: 

100.00 

MASK: 

none 

MAI’: 

geology  in  PERMANENT 

Category  Information 

# 

description 

0 

no  data 

415.13 

0.65 

1 

metainorphic 

2597.02 

4.06 

1 

transition 

32.12 

0.05 

3 

igneous 

811724 

12.68 

4 

sandstone 

16691.60 

26.08 

5 

limestone 

13681.93 

2138 

6 

shale 

10304.07 

16.10 

7 

sandy  shale 

2517.95 

3.93 

8 

claysand 

3229.60 

5.05 

9 

sand 

8141.95 

12.72 

TOTAL 

NOTES 

If  the  user  nms  r.report  interactively  and  saves  the  report  output  in  a  file,  this  file  will  be  placed  into 
the  user’s  current  working  directory. 

If  the  user  nuts  r.report  non-interaclivcly,  report  output  can  be  saved  bv  redirecting  it  to  a  file  or  a 
printer  using  the  UNIX  redirection  mechanism. 

SEE  ALSO 

g.  region,  r.coin,  r. describe,  r.info,  r.mask,  r. slats 

AUTHOR 

Michael  Shapiro.  U  S.  Army  Conslniction  Engineering  Research  Ialx>ratorv 
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NAME 

r. resample  -  GRASS  raster  map  layer  data  resampling  capability. 

(GRASS  Raster  Program) 

SYNOPSIS 

rjreaample 
r  .resample  help 

r .resample  [-q]  input  =no/ne  output  =name 
DESCRIPTION 

r.re sample  resamples  the  data  values  in  a  user-specified  raster  input  map  layer  name  (bounded  by  the 
current  geographic  region  and  masked  by  the  current  mask),  and  produces  a  new  raster  output  map 
layer  name  containing  the  results  of  the  resampling.  The  category  values  in  the  new  raster  output  map 
layer  will  be  the  same  as  those  in  the  original,  except  that  the  resolution  and  extent  of  the  new  raster 
output  map  layer  will  match  those  of  the  current  geographic  region  settings  (see  gjregion). 

The  program  will  be  run  non-interac lively  if  the  user  specifies  program  arguments  on  the  command 
line,  using  the  form 

r  .resample  [*q]  input  name  output  -name 

where  the  input  name  is  the  name  of  the  raster  map  layer  whose  data  are  to  be  resampled,  the  output 
name  is  the  name  of  the  raster  map  layer  to  store  program  output,  and  the  -q  option,  if  present,  directs 
that  r. resample  run  quietly  (supressing  the  printing  of  program  messages  to  standard  output). 

Alternately,  the  user  can  simply  type  r .resample  on  the  command  line,  without  program  arguments. 
In  this  case,  the  user  will  be  prompted  for  needed  inputs  and  option  choices  using  the  standard  GRASS 
parser  interface  described  in  the  manual  entry  for  parser. 

NOTES 

The  method  by  which  resampling  is  conducted  is  "nearest  neighbor"  (see  rjieighbors).  The  resulting 
raster  map  layer  will  have  the  same  resolution  as  the  resolution  of  the  current  geographic  region  (set 
using  g. region). 

The  resulting  raster  map  layer  may  be  identical  to  the  original  raster  map  layer.  The  r.re  sample 
program  will  copy  the  color  table,  category  file,  and  history  file  associated  with  the  original  raster  map 
layer  for  the  resulting  raster  map  layer. 

When  the  user  resamples  a  GRASS  reclass  file,  a  true  raster  file  is  created  by  rsesample. 

SEE  ALSO 

g.region,  rjnapcalc,  r.mask,  r.mfilter,  r. neighbors,  r. rescale,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r. rescale  -  Rescales  the  range  of  category  values  in  a  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

rxescale 
r .rescale  help 

rxescale  [-q]  input  =name  [from  =min,max)  output  =name  [to=rmn,max]  \ 

[title  ="  phrase"] 

DESCRIPTION 

Ihe  r. rescale  program  rescales  the  range  of  categoiy  values  appearing  in  a  raster  map  layer.  A  new 
raster  map  layer,  and  an  appropriate  category  file  and  color  table  based  upon  the  original  raster  map 
layer,  are  generated  with  category  labels  that  reflect  the  original  category  values  that  produced  each 
category.  Ihis  command  is  useful  for  producing  representations  with  a  reduced  number  of  categories 
from  a  raster  map  layer  with  a  laige  range  of  category  values  (eg.,  elevation).  Rescaled  map  layers  are 
appropriate  for  use  in  such  GRASS  programs  as  r stats,  r. report,  and  r.coin. 

r.rescale  will  lx;  nut  non- interactively  if  the  user  specifies  program  arguments  on  the  command  line, 
using  the  form: 

rxescale  [-q]  input  name  [from  =min,max\  output  —name  [to  =min,max]  \ 

[title =' phrase") 

Alternately,  the  user  can  simply  type: 

rxescale 

on  the  command  line  withcxit  program  arguments.  In  this  case,  the  user  will  be  prompted  for  parameter 
values  using  the  standard  GRASS  user  interface  described  in  the  manual  entry  for  parser. 

Flag: 

-<l 

Parameters: 
input  name 
from  nun, max 

output  mante 
to  =nin,max 

title  -"phrase" 

EXAMPLE 

To  rescale  an  elevation  raster  map  layer  with  category  values  ranging  from  1090  meters  to  RS00  meters 
into  the  range  1  255,  tire  following  command  line  could  be  used: 

rxescale  input  ^elevation  from  =1090,1800  output  =elevation-255  to=l,255 

NOTES 

llie  rescaled  category  v;iJuo  range  is  actually  unlimited,  Uit  tire  category  value  range  1  to  255  is 
frequently  used  due  to  limitations  of  color  graphics  monitors. 

(ategory  values  tliat  fall  beyond  the  input  range  will  become  zero.  Ihis  allows  the  user  to  select  a 
subset  of  the  lull  category  value  range  for  rescaling  if  desired.  This  also  means  that  the  user  slxxild 
know  the  category  value  range  for  the  input  raster  map  layer.  Ihe  user  can  request  tlx  r.rescale 


Run  quietly,  without  printing  messages  on  program  progress  to  tire  user's 
terminal. 

Ihe  name  of  the  raster  map  layer  whose  category  values  are  to  be  rescaled. 

Ihe  input  map  range  to  be  rescaled. 

Default:  The  full  range  of  the  input  map  layer. 

Ihe  name  of  the  new,  rescaled  raster  map  layer. 

Ihe  output  map  range  (after  rescaling). 

Default:  1,255 

Title  for  new  output  raster  map  layer. 
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program  to  determine  this  range,  or  can  obtain  it  using  the  r. describe  command.  If  the  category  value 
range  is  determined  using  r. rescale,  the  input  raster  map  layer  is  examined,  and  the  minimum  and 
maximum  non-zero  category  values  are  selected  as  the  input  range. 

SEE  ALSO 

r.coin,  r. describe,  r.mapcalc,  r. reclass,  r. report,  r. resample,  rjiats,  and  parser 
AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r. slope. aspect  -  Generates  raster  map  layers  of  slope  and  aspect  from  a  raster  map  layer  of  true 
elevation  values. 

(GRASS  Raster  Program) 

SYNOPSIS 

rjloptauped 
r .slope .aspect  help 

r  .si  ope  .aspect  [-aqz]  elevation  name  [slop e=name]  [  aspect  name  ] 

DESCRIPTION 

r. slope. aspect  generates  raster  map  layers  of  slope  and  aspect  from  a  raster  map  layer  of  true  elevation 
values.  The  user  must  specify  the  input  elevation  file  name  and  at  least  one  output  file  name  to  contain 
the  slope  or  aspect  data. 

Ihe  program  will  be  run  non- interactively  if  the  user  specifies  program  inputs  and  any  desired  options 
on  the  command  line,  using  the  form 

r.sl  ope  .aspect  [-aq]  elevation  jiame  [slope  =name]  [  aspect  =name] 

If  the  user  runs: 

r.sl  ope  .aspect 

without  command  line  arguments,  the  program  will  prompt  the  user  for  flag  settings  and  parameter 
values. 


Flags; 

-a 


-q 


Parameters: 


Do  not  align  the  settings  of  the  current  geographic  region  (to  which  the  output 
slope  and  aspect  map  layers  will  be  set)  to  those  of  the  elevation  layer.  See 
NO  ITS. 

Run  quietly,  and  suppress  the  printing  of  information  on  program  operations 
during  execution. 

Assume  that  zero  values  in  the  elevation  map  layer  represent  true  elevation 
values,  not  areas  of  "no  data." 


elevation  =name  Name  of  the  raster  map  layer  of  true  elevation  values  to  be  used  as  input, 
slope  =name  Name  of  a  raster  map  layer  of  slope  values  created  from  the  elevation  map. 

aspect  name  Name  of  a  raster  map  layer  of  aspect  values  created  from  the  elevation  map. 

Resulting  raster  map  layers  of  slope  and  aspect  are  named  by  the  user  and  placed  in  the  current  mapset. 


ELEVATION  RASTER  MAP 

lhc  raster  elevation  map  layer  specified  by  the  user  must  contain  true  elevation  values,  not  rescaled  or 
categorized  data. 


ASPECT  RASTER  MAP 

Ihe  raster  aspect  map  layer  w  hich  is  created  indicates  the  direction  that  slopes  are  facing,  lire  .aspect 
categories  arc  as  follows: 
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0  no  data 

1  east  facing 

2  15  degrees  north  of  east 

3  30  degrees  north  of  east 

4  northeast  facing 

5  30  degrees  east  of  north 

6  15  degrees  east  of  north 

7  north  facing 

8  15  degrees  west  of  north 

9  30  degrees  west  of  north 

10  northwest  facing 

11  30  degrees  north  of  west 

12  15  degrees  north  of  west 

13  west  facii^ 

14  15  degrees  south  of  west 

15  30  degrees  south  of  west 

16  southwest  facing 

17  30  degrees  west  of  south 

18  15  degrees  west  of  south 

19  south  facing 

20  15  degrees  east  erf  south 

21  30  degrees  east  erf  sexith 

22  southeast  facing 

23  30  degrees  sexith  of  east 

24  15  degrees  south  of  east 

25  no  aspect  (flat) 

Categexy  and  color  table  files  are  also  generated  for  the  aspect  map  layer. 

SLOPE  RASTER  MAP 

The  resulting  raster  slope  map  layer  will  contain  slope  values,  stated  in  elegrees  of  inclination  from  the 
horizontal.  Categexy  0  will  be  reserved  for  no  eiata.  Categexy  1  will  represent  areas  with  0  elegrees 
slope,  categexy  2  will  represent  areas  with  1  degree  of  sle>pe,  etc.  Tire  slope  map  layer  cexild  contain, 
in  theexy,  up  to  91  categexies.  The  categexy  hie,  but  not  the  eerier  table,  is  generated  by  r Mope. aspect 
for  the  raster  slope  map  layer. 

Often  slope  is  represented  in  percent  rise.  The  following  table  shows  ccxwersion  values  from  elegrees  to 
percent  rise: 
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deg 

perc 

perc 

deg 

perc 

deg 

perc 

deg 

perc 

deg 

perc 

() 

0 

15 

27 

30 

58 

45 

100 

60 

173 

75 

373 

1 

o 

16 

29 

31 

60 

46 

104 

61 

180 

76 

401 

2 

3 

17 

31 

32 

62 

47 

107 

62 

188 

77 

433 

3 

5 

18 

32 

33 

65 

48 

111 

63 

1% 

78 

470 

4 

7 

19 

34 

34 

67 

49 

115 

64 

205 

79 

514 

5 

9 

20 

36 

35 

70 

50 

119 

65 

214 

80 

567 

6 

11 

21 

38 

36 

73 

51 

123 

66 

225 

81 

631 

7 

12 

22 

40 

37 

75 

52 

128 

67 

236 

82 

712 

8 

14 

23 

42 

38 

78 

53 

133 

68 

248 

83 

814 

9 

16 

24 

45 

39 

81 

54 

138 

69 

261 

84 

951 

10 

18 

25 

47 

40 

84 

55 

143 

70 

275 

85 

1143 

11 

19 

26 

49 

41 

87 

56 

148 

71 

290 

86 

1430 

12 

21 

27 

51 

42 

90 

57 

154 

72 

308 

87 

1908 

13 

23 

28 

53 

43 

93 

58 

160 

73 

327 

88 

2864 

14 

25 

29 

55 

44 

97 

59 

166 

74 

349 

89 

5729 

90  (undefined) 

Iixvever,  for  most  applications,  the  user  will  wish  to  use  a  reclassified  map  layer  of  slope  that  groups 
slope  values  into  ranges  of  slope.  This  can  be  done  using  r. reclass.  An  example  of  a  useful 
reclassification  is  given  below: 


category 

range 

(in  degrees) 

category  labels 
(in  percent) 

1 

0-1 

0-2% 

2 

2-3 

3-5% 

3 

4-5 

6-10% 

4 

6-8 

11-15% 

5 

9-11 

16-20% 

6 

12-14 

21-25% 

7 

15-90 

26%  and  higher 

The  following  color  table  works  well  with  the  above  reclassification. 


category 

red 

green 

blue 

0 

179 

179 

179 

1 

0 

102 

0 

2 

0 

153 

0 

3 

128 

153 

0 

4 

204 

179 

0 

5 

128 

51 

5i 

6 

255 

0 

0 

7 

0 

0 

0 

To  ensure  that  the  raster  elevation  map  layer  is  in >t  inappropriately  resampled,  the  settings  for  the 
current  region  are  nuxlificd  slightly  (fix  the  execution  of  the  program  ool \' ) :  tire  resolution  is  set  to 
match  tlx-  resolution  of  the  delation  map  and  the  edges  of  the  region  (i.e.,  the  north,  south,  east  and 
west)  are  shilled,  if  necessary,  to  line  up  along  edges  of  the  nearest  cells  in  tlx:  elevation  map.  If  the 
user  really  wants  the  elevation  map  resampled  to  the  current  region  resolution,  the  -a  11. t:  should  Iv 
s|x-cificd. 
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The  current  mask,  if  set,  is  ignored. 

The  algorithm  used  to  determine  slope  end  aspect  uses  a  3x3  neighborhood  around  each  cell  in  the 
elevation  file.  Thus,  it  is  not  possible  to  determine  slope  and  aspect  for  the  cells  adjacent  to  the  edges 
in  the  elevation  map  layer.  These  cells  are  assigned  a  "no  data"  value  (category'  zero)  in  both  the  slope 
and  aspect  raster  map  layers. 

WARNING 

Elevations  of  zero  (as  well  as  below  sea  level  elevations)  are  valid.  This  means  that  areas  assigned 
category  value  zero  may  have  one  of  two  possible  meanings:  they  may  either  be  areas  of  "no  data"  or 
areas  having  zero  elevation.  If  the  user  wishes  r  Mope  .aspect  to  assume  that  cells  assigned  category 
value  zero  in  the  elevation  map  layer  represent  true  elevation  values,  not  areas  of  "no  data",  the  user 
should  set  the  -z  flag  when  running  this  program. 

If  the  -z  flag  is  not  set  and  the  raster  map  layer  of  true  elevation  contains  areas  of  "no  data"  that  are 
assigned  to  category  zero,  either  at  its  edges  or  in  its  interior,  incorrect  (and  usually  quite  large)  slopes 
will  result. 

SEE  ALSO 

r.mapcalc,  r neighbors,  r.reclass,  r.rescale 

AUTHORS 

Michael  Shapiro,  U  S.  Army  Construction  Engineering  Research  Laboratory 
Marjorie  Larson,  U.S.  Army  Construction  Engineering  Research  I aboratory 
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NAME 

r.stats  -  Generates  area  statistics  for  raster  map  layers. 

(GRASS  Rosier  Program) 

SYNOPSIS 

ratals 
r.stats  help 

r .stats  [-lacmqzgx]  input  =name[/iame,...}  [f*=character  | space]  [output  =name] 

DESCRIPTION 

r.stats  calculates  the  area  present  in  each  of  the  categories  of  user-selected  raster  map  layers).  Area 
statistics  can  be  given  in  units  of  acres,  hectares,  square  miles,  and  cell  counts.  This  analysis  uses  the 
current  geographic  region  and  mask  settings.  Output  can  be  sent  to  a  file  in  the  user’s  current  working 
directory . 

llie  program  will  be  nin  non-interactively  if  the  user  specifies  the  program  arguments  a.id  desired 
options  on  the  command  line,  using  the  form 

r .stats  [-lacmqzgx]  input  =name[/iame,...}  [h=character  | space]  [output  =name\ 

where  each  input  name  is  the  name  of  a  raster  map  layer  on  which  area/cell  statistics  are  to  be 
generated,  the  (optional)  output  name  is  the  name  of  a  file  to  contain  program  output  (sent  to  the  user’s 
current  working  directory  ),  the  fs  character  or  space  is  the  field  separator  to  be  used  to  separate  data 
fields  in  the  output  file  (default  is  a  space  if  uns">ecified),  and  the  (optional)  flags  -7,  -a,  -c,  -m,  -q,  -z, 
-g,  and  -x  have  the  meanings  described  in  the  OPTIONS  section. 

Alternately,  the  user  can  simply  type  r.stats  on  the  command  line,  without  program  arguments.  In  this 
case,  the  user  will  be  prompted  (  needed  inputs  and  option  choices  using  the  standard  GRASS  parser 
interface  described  in  the  manual  entry  for  parser. 

OPTIONS 

Flags: 

-1 


c 

-m 

-q 

-z 


-R 

-x 

input 


The  cL' tor  each  cell  in  the  current  geographic  region  will  be  output,  one  cell  per 
line,  rath  r  than  the  totals  for  each  distinct  combination.  Also  prints  the 
geographic  coordinates  (earwigs,  and  northings)  associated  with  each  cell. 

Print  area  totals. 

Print  total  cell  counts. 

Report  zero  values,  because  a  mask  is  present  and  the  user  is  interested  in  zero 
data  values  falling  within  the  mask. 

Run  quietly,  and  supress  printing  of  percent  complete  messages  to  standard 
output. 

Report  only  non-zero  data  values.  Zero  data  will  not  be  output.  For  multiple 
map  layers  this  means  that  zero  category  valuer  in  every  map  layer  will  not  be 
output;  non-zero  category  values  in  any  map  layer  will  be  output. 

Print  the  grid  coordinates  (easliig  and  northing),  for  each  cell.  This  option  works 
only  if  the  l  option  is  also  specified. 

lYint  the  x  ;uxl  y  (column  and  row)  values,  for  each  cell.  This  option  works  only 
if  the  -1  option  is  also  specified.  Parameters: 

- name  lhc  namc(s)  of  one  or  more  existing  raster  map  layers)  whose  cell  counts  or  area 

statistics  arc  to  lie  calculated. 
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fs  =character  or  ts=space 

The  field  separator  (fs)  to  be  used  to  separate  data  fields  in  the  output  file. 
Options:  a  character  or  space 
Default:  a  space 

output  The  name  to  be  assigned  to  the  ASCII  output  file. 

NON-INTERACITVE  PROGRAM  USE 

If  users  invoke  program  options  cm  the  command  line,  rjstats  will  print  out  area  statistics  for  the  user- 
specified  raster  map  layers  in  a  columnar  format  suitable  for  input  to  UNIX  programs  like  awk  and  sed. 
Output  can  be  saved  by  specifying  the  name  of  an  output  file  or  *he  command  line. 

If  a  single  map  layer  is  specified  on  the  command  line,  a  list  of  areas  in  square  meters  (assuming  the 
map’s  coordinate  system  is  in  meters)  for  each  category  in  the  raster  map  layer  will  be  printed.  (If  the 
-c  option  is  chosen,  areas  will  be  stated  in  number  of  cells.)  If  multiple  raster  map  layers  are  specified 
on  the  command  line,  a  cross- tabulation  table  of  areas  for  each  combination  of  categories  in  die  map 
layers  will  be  printed. 

For  example,  if  cme  raster  map  layer  were  specified,  the  output  would  lot*  like: 

1:1350000.00 

2:4940000.00 

3:8870000.00 

If  three  raster  map  layers  a,  b,  and  c,  were  specified,  the  output  would  look  like: 

0:0:0:8027500.00 

1.0:0:164227500.00 

20:0-31277500.00 

30:0:17140000.00 

1:0:12177500.00 

20:1:2490000.00 

0:1:0:1152500.00 

1:10:140092500.00 

2:10:24207500.00 

3:1:0:11270000.00 

1:1:13355000.00 

2:1:1:1752500.00 

3:1:1:2500.00 


Within  each  grouping,  the  first  field  represents  the  category  value  of  map  layer  a,  the  second  represents 
the  category  values  associated  with  map  layer  b,  the  third  represents  category  values  for  map  layer  c, 
and  the  last  field  gives  the  area  in  square  meters  for  the  particular  combination  of  these  three  map 
layers’  categories.  For  example,  above,  combination  3,1,1  covered  2500  square  meters.  Reids  arc 
separated  by  colons. 

NOTES 

r. stats  works  in  the  current  geographic  region  with  the  current  mask. 

If  a  nicely  formatted  output  is  desired,  pipe  the  output  into  a  command  which  can  create  columnar 
output.  For  example,  the  command: 

r.stats  input  =a,b,c  |  pr  -3  |  cat  -s 

will  create  a  three-column  output 
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1 : 4 : 4 : 10000  .00 
1 4:5:1340000.00 
2:1:1:1090000.00 
2:1:3:410000.00 


2:1:5:290000.00 

2:2:5:350000.00 

2:4:1:700000.00 

2:4:3:10000.00 


2:4:5:2090000.00 
3:1:2:450000.00 
3 : 1 :3 : 5280000 .00 
3:1  :5 :3140000 .00 


Also,  the  output  in  the  examples  given  happen  to  be  in  sorted  order,  but  the  output  from  r. stats  cm 
more  than  one  map  layer  is  not  guaranteed  to  be  in  any  particular  order.  If  the  user  desires  sorted 
output,  use  the  UNIX  sort  command.  For  example- 

r.stats  input  nj),c  |  sort  -t:  -On 

Note  that  the  user  has  only  the  option  of  printing  out  cell  statistics  in  terms  of  cell  counts  and/or  area 
totals.  Users  wishing  to  use  different  units  than  are  available  here  should  use  the  GRASS  program 
r. report. 

SEE  ALSO 

g.  region,  r.coin,  r. describe,  r. report,  aid  parser 
AUTHORS 

Michael  O’  Shea,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r support  -  Allows  the  user  to  create  and/or  modify  raster  map  layer  support  files. 

(GRASS  Raster  Program) 

SYNOPSIS 

r^upport 

DESCRIPTION 

The  GRASS  program  r support  allows  the  user  to  create  and/or  modify  raster  map  layer  support  files. 
It  may  be  run  only  on  raster  map  layers  in  the  user's  current  mapset. 

No  non- interactive  version  of  this  program  currently  exists;  the  user  runs  the  program  by  typing 
r .support,  and  will  be  queried  for  inputs. 

Various  GRASS  programs  depend  on  one  or  more  of  the  following  GRASS  support  files: 

cellbd  The  cell  header  file  contains  information  on  a  map’s  projection,  zone,  regional  boundaries, 
row  and  column  totals,  cell  resolution,  storage  format,  and  compression.  It  describes  where 
and  how  this  map’ s  raster  (cell)  data  fits  in  with  reference  to  other  raster  map  layers’  data. 
Without  it,  the  raster  map  layer  could  not  be  displayed  or  analyzed  properly.  Using 
r support,  the  user  can  charge  the  # of  columns,  #of  bytes  per  cell,  and  default  geographic 
region  settings.  Generally,  users  would  not  change  this  information.  Cell  header  files  are 
stored  under  the  cellhd  directory  under  the  user’s  current  mapset. 

stats  Raster  map  layer  statistics  are  saved  in  the  form  of  a  histogram  and  range  of  the  category' 
values  that  occur  in  the  map  layer.  Statistics  files  are  stored  in  subdirectories  of  the 
cell_rrusc  directory  under  the  user’s  current  mapset. 

cats  A  category  file  associates  each  category  value  in  the  raster  map  layer  with  a  category 

description  (label).  The  user  may  add  or  edit  the  category  descriptions,  alter  the  number  of 
categories,  and  add  or  alter  the  map's  title.  Category  files  associated  with  raster  map  layers 
are  stored  under  the  cats  directory  in  the  user’s  current  mapset. 

coir  A  color  file  associates  each  category  value  in  the  raster  map  layer  with  a  color.  Using 

r support,  the  user  may  assign  one  of  eight  color  table  types  to  the  raster  map  layer.  Map 
color  table  files  are  stored  under  the  coir  and  colr2  directories  under  the  user’s  current 
mapset. 

hist  Historical  information  about  the  raster  map  layer  is  stored  in  a  history  file.  The  user  may 

add  or  edit  the  raster  map’s  title,  data  type,  data  source,  data  description,  and  include 
comments.  (Note  that  the  specification  of  map  data  type  here  is  somewhat  archaic,  and 
should  always  be  set  to  raster .)  Map  history  files  are  stored  under  tlie  hist  directory'  under 
the  user’s  current  mapset. 

NOTES 

The  rsupport  program  attempts  to  verify  that  the  information  in  the  cell  header  is  reasonable.  The 
data  format  specified  in  the  header  is  verified  against  the  raster  map  layer  itself.  This  includes  checking 
that  files  that  the  header  indicates  are  compressed  are  really  compressed,  and  that  tlie  number  of  rows 
and  columns  specified  in  the  header  correspond  to  the  actual  file  size. 

The  rsupport  program  can  also  be  used  to  determine  the  number  of  columns  ami  rows  of  data  in  a 
raster  map  layer,  in  the  event  that  no  cell  header  is  available  This  is  useful,  for  example,  fir  importing 
raster  map  layers  created  by  software  oilier  tlian  GRASS. 

If  the  file  is  not  compressed,  the  file  size  should  be  the  product  of  the  number  of  row  s  and  columns.  If 
tlie  file  is  compressed,  this  test  cannot  be  performed  since  the  file  size  will  Ix^ir  no  relation  to  the 
product.  The  number  of  rows  can  still  lie  verified,  but  tlie  number  of  columns  cannot. 
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To  compute  or  correct  the  stats ,  the  cell  header  must  be  correct,  since  the  raster  map  layer  is  read  to 
determine  the  stats. 

If  a  new  cats  or  coir  (or  colr2)  file  is  required,  the  stats  must  lie  correct. 

The  user  is  allowed  to  change  the  number  of  categories  specified  in  the  category  file.  This  should  only 
be  done  if  the  user  knows  that  the  maximum  category  value  in  the  raster  map  layer  is  different  than 
that  which  is  recorded  in  the  category  file.  Changing  the  category  value  in  the  cats  file  allows  the  user 
to  add  more  category  labels,  or  to  remot  e  labels.  It  does  NOT  change  the  category  values  in  the  raster 
map  layer  itself. 

The  color  file  is  unique  among  GRASS  support  files.  While  it  is  necessary  to  protect  a  user’s  original 
data  from  being  modified  by  users  working  under  other  mapsets,  these  users  need  to  be  able  to  create 
color  tables  for  maps  that  are  stored  under  mapsets  other  than  their  own.  Color  table  files  meet  both 
these  objectives. 

Color  table  files  get  stored  in  one  of  two  directories,  both  under  the  user’s  current  mapset.  The  color 
files  created  by  a  user  for  raster  maps  stored  under  that  user’s  current  mapset  get  stored  in  the  directory 
SljOCA'IlON/colr  and  cannot  be  modified  or  removed  by  other  users.  The  color  table  files  that  the 
user  modifies/creates  for  raster  map  layers  not  stored  under  the  user’s  current  mapset  get  stored  in  a 
secondary  color  file  under  the  user’s  mapset.  This  secondary  color  table  is  stored  under 
$ l X)CATION/colr2/<tnapset>  where  <Tnapset>  is  the  name  of  the  mapset  under  which  the  raster  map 
i.iata  are  stored.  In  versions  of  GRASS  prior  to  3.0,  this  was  also  the  case  for  color  tables  in  the  user’s 
own  mapset.  Now,  however,  if  a  user  modifies  a  color  table  associated  with  a  raster  map  layer  in  his 
own  current  mapset.  these  charges  will  be  made  to  the  user’s  original  color  file  (i.e.,  the  user’s  color 
changes  will  overwrite  whatever  previous  color  table  file  existed  for  this  map  under  the  user’s 
$ iJOCATION/colr  directory).  No  secondary  color  files  are  created  for  raster  map  layers  stored  in  the 
user's  own  mapset. 

WARNING 

In  order  to  modify  the  cell  header,  the  raster  (cell)  map  layer  under  consideration  must  not  be  a 
reclass  file.  This  is  because  the  reclass  file’s  header  does  not  contain  positional  information,  but 
rather  a  reference  to  another  raster  map  layer.  Thus  it  shares  a  cell  header  with  the  referenced  raster 
map  layer.  In  order  to  change  the  cell  header,  r. support  must  be  run  on  the  true  raster  file  referenced. 

SKK  ALSO 

Lor  more  information  regarding  the  location  and  function  of  GRASS  support  files,  consult  the  GRASS 
Programmer’s  Manual  chapter  on  "GRASS  Database  Structure.” 

d.colors,  r. colors,  r. reclass 

AUTHOR 

Michael  Shapiro,  U  S.  Anny  Construction  Engineering  Research  Laboratory 
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NAME 

rjurf. contour  -  Surface  generation  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

rjurfxontour 
r .surf .contour  help 

rjurfxontour  [-f]  input  name  output  name 
DESCRIPTION 

rjurf.contour  creates  a  raster  elevation  map  from  a  rasterized  contour  map.  Elevation  values  are 
determined  using  procedures  similar  to  manual  methods.  To  determine  the  elevation  of  a  point  on  a 
contour  map,  an  individual  might  interpolate  its  value  from  those  of  the  two  nearest  contour  lines 
(uphill  and  downhill). 

rjurfxontour  works  in  a  similar  way.  Initially,  a  vector  map  of  the  contour  lines  is  made  with  the 
elevation  of  each  line  as  its  label  (see  v. digit).  When  the  program  v.tojrast  is  run  on  tire  vector  map, 
continuous  "lines"  of  rasters  containing  the  contour  line  values  will  be  the  input  for  rjurfxontour. 
For  each  cell  in  the  input  map,  cither  the  cell  is  a  contour  line  cell  (which  is  given  that  v  alue),  or  a 
flood  fill  is  generated  from  that  spot  until  the  fill  comes  to  two  unique  values.  Ihc  flood  fill  is  not 
allowed  to  cross  over  the  rasterized  contour  lines,  thus  ensuring  that  an  uphill  and  downhill  contour 
value  will  be  the  two  values  chosen,  rjurfxontour  interpolates  from  the  uphill  and  downhill  values  by 
the  tree  distance. 

The  program  will  be  mn  non- interactively  if  the  user  specifies  the  program  parameter  values  and 
desired  flag  settings  on  the  command  line,  using  the  form: 

rjurfxontour  [-f]  input  name  output  name 

Alternately,  the  user  can  simply  type  r.surf .contour  on  the  command  line,  without  program 
arguments.  In  this  case,  the  user  will  be  prompted  for  needed  inputs  and  option  choices  usit^  the 
standard  GRASS  user  interface  described  in  the  manual  entry  for  parser. 

Flag: 

-f 

Parameters: 
input  =name 

output  =name 


NOTES 

rjurfxontour  works  well  under  the  following  circumstances:  1)  the  contour  lines  extend  to  the  edge  of 
the  current  region,  2)  the  program  is  mn  at  the  same  resolution  as  that  of  the  input  map,  3)  there  are  no 
disjointed  contour  lines,  and  4)  no  spot  elevation  data  BE1WI-EN  contour  lines  exist.  Spot  elevations 
at  the  tops  of  hills  and  the  bottoms  of  depressions,  on  the  other  hand,  improve  the  uttput  greatly. 
Violating  these  constraints  will  cause  non- intuitive  anouKtlies  to  ap^rcar  in  the  <xitput  map.  Run 
rjlope.aspect  on  r.surf  .contour  results  to  locate  potential  anomalies. 

The  running  of  rjurfxontour  is  very  sensitive  to  the  resolution  of  rasterized  vector  map.  If  multiple 
contour  lines  go  through  the  same  raster,  slight  anomalies  may  occur.  The  sjteed  of  rjurfxontour  is 
dependent  on  lxw  lar  "apart”  the  contour  lines  arc  from  each  other  (as  measured  in  rasters).  Since  a 
flood  All  algorithm  is  used,  the  program’s  naming  time  will  grow  exponentially  with  tin:  distance 
between  contixtr  lines. 


Invoke  fast,  but  memory-intensive  program  operation. 

Name  of  an  existing  raster  map  layer  that  contains  a  set  of  initial  category  values 
(i.e.,  some  cells  contain  knewn  category'  values  (denoting  contours)  while  the  rest 
contain  zeros  (0)). 

Name  to  be  assigned  to  new  output  raster  map  layer  that  represents  a  smooth 
(e.g.,  elevation)  sttrface  generated  from  the  known  category  values  in  the  input 
raster  map  layer. 
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SEE  ALSO 

rsurf.idw,  rjurf.idw2,  sjurfjdw,  v. digit,  vjojrast,  r Mope. aspect,  and  parser 
AUTHOR 

Chuck  Ehlschlaeger,  U  S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

rjurfAdw  -  Surface  interpolation  utility  for  raster  map  layers. 

SYNOPSIS 

rjairf-idw  [-ej  inpat  name  output  =rua/ne  [npoints=va/ue] 

DESCRIPTION 

r.surf.idw  fills  a  grid  cell  (raster)  matrix  with  interpolated  values  generated  from  a  set  of  input  layer 
data  points.  It  uses  a  numerical  approximation  technique  based  on  distance  squared  weighting  of  the 
values  of  nearest  data  pants.  The  number  of  nearest  data  points  used  to  determine  the  interpolated 
value  of  a  cell  can  be  specified  by  the  user  (default:  12  nearest  data  points). 

If  there  is  a  current  working  mask,  it  applies  to  the  output  raster  file.  Only  those  cells  falling  within  the 
mask  will  be  assigned  interpolated  values.  The  search  procedure  for  the  selection  of  nearest 
neighboring  points  will  consider  all  input  data,  without  regard  to  the  mask. 

The  command  line  input  is  as  follows: 


Flag: 


Parameters: 
input  =name 


output  name 
npoints  =value 


Error  analysis  option  that  interpolates  values  only  for  those  cells  of  the  input 
raster  map  which  have  non- zero  values  and  outputs  the  difference  (see  NOTES 
below). 


Name  of  an  input  raster  map  layer  containing  an  incomplete  set  of  data  values, 
(i.e.,  some  grid  cells  contain  known  data  values  while  the  rest  contain  zero  [0]). 

Name  to  be  assigned  to  new  output  raster  map  that  represents  the  surface 
generated  from  the  known  data  values  in  the  input  layer. 

Number  of  nearest  data  points  used  to  determine  the  interpolated  value  of  an 
output  raster  cell. 

Default:  12 


NOTES 

rjurf.idw  is  a  surface  generation  utility  which  uses  inverse  distance  squared  weighting  (as  described  in 
Applied  Geoatati sties  by  E.  EL  Isaaks  and  R.  M.  Srivastava,  Oxford  University'  Press,  1989)  to  assign 
interpolated  values.  Ihe  implementation  includes  a  customized  data  structure  somewhat  akin  to  a 
sparse  matrix  which  enhances  the  efficiency  with  which  nearest  data  points  are  selected.  For 
latitude/longitude  projections,  distances  ;tre  calculated  from  point  to  point  along  a  geodesic. 


Unlike  r.surf.idw2,  which  processes  all  input  data  points  in  each  interpolation  cycle,  r.surf.idw  attempts 
to  minimize  the  number  of  input  (Lata  for  which  distances  must  be  calculated.  Execution  sjved  is 
therefore  a  function  of  the  search  effort,  and  does  not  increase  appreciably  with  the  number  of  input 
data  points. 


r.surf.idw  will  generally  outperform  r.surf.idw2  except  when  the  input  data  layer  contains  few  noiv 
zero  data,  i.e.,  when  the  cost  of  the  search  exceeds  the  cost  of  the  additional  distance  calculations 
performed  by  r.surf.idw2.  Ihe  relative  performance  of  these  utilities  will  depend  on  the  comparative 
speed  of  boolean,  integer,  and  floating  point  operations  on  a  particular  platform. 

Worst  case  search  performance  by'  rjurf.idw  occurs  when  the  inteqiolatecl  cell  is  located  outside  of  the 
region  in  which  input  (Lita  are  distributed.  It  therefore  liehooves  the  user  to  employ  a  mask  when 
geographic  region  boundaries  include  large  areas  outside  tlx;  general  extent  of  the  input  data. 
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lhe  degree  of  smoothing  jiroduced  by  the  interpolation  will  increase  relative  to  the  number  erf  nearest 
data  points  considered,  lhe  utility  may  be  used  with  regularly  or  irregularly  spaced  input  data. 
However,  the  output  result  for  the  former  may  include  unacceptable  nonconformities  in  the  surface 
pattern. 

The  -e  flag  option  provides  a  standard  surface-generation  error  analysis  facility,  ft  produces  an  output 
raster  map  of  the  difference  of  interpolated  values  minus  input  values  for  those  cells  whose  input  data 
are  non-zero.  For  each  interpolation  cycle,  the  known  value  erf  the  cell  under  consideration  is  ignored, 
and  the  remaining  input  values  are  used  to  interpolate  a  result.  The  output  raster  map  may  be 
compared  to  the  input  raster  map  to  analyze  the  distribution  of  interpolation  error.  This  procedure  may 
be  helpful  in  choosing  the  number  of  nearest  neighbors  considered  for  surface  generation. 

SEE  ALSO 

r. surf. contour,  rjurf.idw2,  sjurfjdw,  and  parser 

AUTHOR 

Greg  Koerper  (Oregon  State  University) 

Goixi]  Climate  Research  Project 

U  S.  EPA  Environmental  Research  Laboratory 

200  S.W.  35th  Street,  JSB 

Corvallis,  OR  97333 

koerper@cs.orst.edu 
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NAME 

rjurf.idw2  -  Surface  generation  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.aurf.idw2  input  -name  output  =vjo/ne  f npoints  =count  j 
DESCRIPTION 

r.surf.idw2  fills  a  raster  matrix  with  interpolated  values  generated  from  a  set  of  irregularly  spaced  data 
points  using  numerical  approximation  (weighted  averaging)  techniques.  The  interpolated  value  of  a  cell 
is  determined  by  values  of  nearby  data  points  and  the  distance  of  the  cell  from  those  input  points.  In 
comparison  with  other  methods,  numerical  approximation  allows  representation  of  more  complex 
surfaces  (particularly  those  with  anomalous  features),  restricts  the  spatial  influence  of  any  errors,  and 
generates  the  interpolated  surface  from  the  data  points.  It  is  the  most  appropriate  method  to  apply  to 
most  spatial  data. 

The  program  will  be  run  non-interactively  if  the  user  specifies  the  values  of  needed  program  parameters 
and  any  desired  optional  parameter  values  on  the  command  line,  using  the  form: 

r -surf id  w  2  input  -name  output  rxame  [  npoints  count  j 

Alternately,  die  user  can  simply  type  rjurfJdw2  on  the  command  line,  without  program  arguments. 
In  this  case,  the  user  will  be  prompted  for  parameter  values  using  the  standard  GRASS  user  interface 
described  in  the  manual  entry'  for  parser. 

Parameters: 

input  -name  Name  of  an  input  raster  map  layer  that  contains  a  set  of  irregularly  spaced  data 

values:  i.e.,  some  cells  contain  known  data  values  while  the  rest  contain  zero  (0). 

output  name  Name  to  be  assigned  to  the  new  output  raster  map  layer  containing  a  smooth 
surface  generated  from  the  known  data  values  in  the  input  map  layer. 

npoints  count  The  number  of  points  to  use  for  interpolation.  The  default  is  to  use  the  12  nearest 
points  when  interpolating  the  value  for  a  particular  cell. 

Default:  12 


NOTES 

The  amount  of  memory  used  by  this  program  is  related  to  the  number  of  non- zero  data  values  in  the 
input  map  layer.  If  tlie  input  raster  map  layer  is  very  dease  (i.e.,  contaias  many  non  zero  data  points), 
the  program  may  not  be  able  to  get  all  the  memory  it  needs  from  the  system.  The  time  required  to 
execute  increases  with  the  number  of  input  data  points. 

If  the  user  has  a  mask  set,  then  interpolation  is  only  done  for  those  cells  that  fall  within  the  mask. 
However,  all  non  zero  data  points  in  the  input  layer  arc  used  even  if  they  fall  outside  the  mask. 

This  program  does  not  w<rk  with  latitude/longitude  data  bases,  Anotlier  surface  generation  program, 
named  r.surf.idw,  should  be  used  with  latitude/longitude  data  bases. 

Ihe  user  should  refer  to  the  manual  entries  for  rjurf.idw ,  r  jurf. contour ,  and  s.surf.idw  to  compare 
tills  surface  generation  program  with  others  available  in  GRASS. 

SEE  ALSO 

r.mask,  r. surf. contour,  r.surf.idw,  ssurf.idw,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  laigincering  Research  I alxxatory 


GRASS  4.0  (Summer  1991) 


U.S.  Army  ( T.RI 


324 


r.thin 


GRASS  Reference  Manual 


r.thin 


NAME 

r.thin  -  Thins  non- zero  cells  that  denote  linear  features  in  a  raster  map  layer. 

(GRASS  Raster  Program) 

SYNOPSIS 

rJbia 
rihia  help 

rihia  input  mame  output  -  name 
DESCRIPTION 

r.thin  scans  the  named  input  raster  map  layer  and  thins  non-zero  cells  dial  denote  linear  features  into 
linear  features  having  a  single  cell  width. 

r.thin  will  thin  only  the  non-zero  cells  of  the  named  input  raster  map  layer  within  the  current 
geographic  region  settings.  The  cell  width  of  the  thinned  output  raster  map  layer  will  be  equal  to  the 
cell  resolution  of  the  currently  set  geographic  region.  All  of  the  thinned  linear  features  will  have  the 
width  of  a  single  cell. 

r.thin  will  create  a  new  output  raster  data  file  containing  the  thinned  linear  features,  r.thin  assumes 
that  linear  features  are  encoded  with  positive  values  on  a  background  of  0’s  in  the  input  raster  data  file. 

Parameters: 

input  name  Name  of  a  raster  map  layer  containing  data  to  be  thinned. 

output  name  Name  of  the  new  raster  map  layer  to  hold  thinned  program  output. 

The  user  can  run  this  y  ograin  either  non-interactively  or  interactively.  The  program  will  be  run  non- 
interactively  if  *’  -r  specifies  pregram  arguments  on  the  command  line,  using  the  form: 

r  .r  pul  name  output -name 

Alternately,  the  user  can  simply  type: 

rAhin 

'*1  the  command  line,  without  program  arguments.  In  this  case,  die  user  will  be  prompted  for  needea 
parameter  values  using  the  standard  GRASS  parser  interface  described  in  die  manual  entry  for  parser. 

NOTES 

r.thin  only  creates  raster  map  layers.  You  will  need  to  run  rjine  on  the  resultant  raster  file  to  create  a 
vector  (i v. digit )  map  layer. 

r.thin  may  create  small  spurs  or  "dangling  lines"  during  the  thinning  process.  These  spurs  may  be 
removed  (after  creating  a  vector  map  layer)  by  vjrim. 

r.thin  creates  a  0/1  output  map. 

This  program  remains  under  alpha  testing.  It  resides  in  the  sir  alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

g.region,  rJine,  v. digit,  v support,  v.trim,  and  parser 

AUTHOR 

Michael  Baba 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

rJraj  -  Ballistic  trajectory  modeling  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

riraj 
riraj  bdp 

riraj  input  name  output  =name  weapon  --name  coordinate  =x,y 

deration  =value  ammunition -name  left  azimuth  name  right  juimuth=name 

DESCRIPTION 

r.traj  generates  a  raster  map  layer  showing  cells  that  can  be  hit  from  a  firing  point  by  shells  from  a 
user-specified  weapon.  Cells  are  marked  with  integer  values  that  represent  the  muzzle  firing  angles 
required  to  hit  them. 

COMMAND  LINE  OPTIONS 
Parameters: 

inpat  =name  Name  of  the  elevation  raster  map. 

output  name  Name  of  new  raster  map  containing  results. 

weapon  -name  Type  of  weapon  used  for  firing.  A  list  of  weapon  types  and  their 

associated  attributes  are  kept  in  the  file  $GlSBASE/weapon_data/weapons. 

coordinate  -x,y  The  coordinates  of  the  firing  point  (east,  north). 

deration  value  Maximum  weapon  muzzle  elevation. 

ammunition  ^name  Type  of  ammunition.  A  list  of  ammunition  types  and  their  associated 

attributes  are  kept  in  the  file  $GISBASFAveapon_data/ammunition. 

lefLazimuth  =name  Far  left  edge  of  allowable  firing  azimuth.  The  angle  will  be  in  the  form  of: 

[NS]0-90[EW] 

For  example,  S60E  indicates  the  angle  is  60  degrees  East  of  true  South. 

right jmmnth  name  Far  right  edge  of  allowable  firing  azimuth,  stated  in  same  form  as 

left  Azimuth. 

Category  values  in  the  output  raster  map  layer  will  program  results.  Category  values  between  -89  and 
89  indicate  the  gun  elevation  angle  in  degrees  needed  to  hit  that  cell.  A  category  value  erf  90  is 
assigned  to  the  weapon’s  firing  point.  A  category  value  of  -90  is  assigned  to  those  points  unhittable  by 
the  weapon. 

EXAMPLE 

r.traj  input  =eleration  output  =name  weapon  Ml  coordinate  =4500000.0/1920000.0 
deration  =2.5  ammunition  =M392  I  eft  .azimuth  S30E  right  -azimuth  =S25W 

WEAPON  AND  AMMUNITION  TYPES 

Weapon  types  and  their  attribute  types  are  listed  below.  These  can  be  listed  by  running  the  program 
r.traj. dot  a. 


Ammunition  types  and  their  attributes  are  listed  below.  These  can  be  displayed  by  running  the  pug  ram 
r.traj. data. 
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Ammo  Type 

M392 

105 

18.60 

1458 

M392A2 

105 

18.60 

1458 

M728 

105 

18.95 

1426 

M735 

105 

23.05 

1501 

M735A1 

105 

1724 

1508 

M774 

105 

1723 

1508 

M494 

105 

24  9 

821 

M456 

105 

21.78 

1173 

M416 

105 

20.68 

737 

M467 

105 

20.42 

730 

M490 

105 

20.41 

1170 

M724 

105 

14.51 

1507 

M724A1 

105 

14.51 

1539 

M737 

105 

9.44 

1539 

M393 

105 

20.41 

732 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  src alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

See  $ GISB ASEi/e tc Av eapon_data/w eapons  for  a  list  of  ammunition  types. 

See  $GISBASE/etcAveapon_data/ammunition  for  a  list  of  ammunition  types. 

d.rast. arrow,  r.los,  r  Mope. aspect,  rjurf. contour,  rsurfjdw  rjsurfjdw2,  r.traj  Mata,  range. place, 
and  parser 

AUTHORS 

Chuck  Ehlschlaeger,  U  S.  Army  Constmction  Engineering  Research  Laboratory 
Kewan  Q.  Khawaja,  Intelligent  Engineering  Systems  Laboratory,  MJ.T. 
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NAME 

r.traj  jiata  -  Reviews  the  airenunition  and  weapon  data  base  used  by  rJraj. 

(GRASS  Raster  Program) 

SYNOPSIS 

rirajulaU 
rirajjUU  help 
rirajjita  [-*w] 

DESCRIPTION 

riraj  uses  ammunition  and  weapon  information  that  can  be  displayed  with  this  program.  Program 
flags  are  listed  below. 

Flag*: 

-m  Prints  list  of  ammunition  types  usable  by  r.traj. 

-w  Prints  list  of  weapons  usable  by  r.traj. 

NOTES 

This  program  remains  under  alpha  testing.  It  resides  in  the  sre alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

r.traj,  and  parser 

AUTHOR 

James  Westervelt,  Construction  Engineering  Research  Laboratory 
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NAMK 

r. transect  -  Outputs  raster  map  layer  values  lying  along  user-defined  transect  line(s). 

(GRASS  Raster  Program) 

SYNOPSIS 

r  transect 
r .transect  help 

r .transect  map  name  [result  =type]  j width  value] 

line  =east, north, azimuth, distance[, east, north, azimJh,distance,...} 

DESCRIPTION 

This  program  outputs,  in  ASCII,  the  values  in  a  raster  map  that  lie  along  one  or  more  user-defined 
transect  lines.  The  transects  are  described  by  their  starting  coordinates,  azimuth,  and  distance.  The 
transects  may  be  single-cell  wide  lines,  or  multi  pie- cell  wide  lines.  The  output,  far  each  transect,  may 
be  the  values  at  each  of  the  cells,  or  a  single  aggregate  value  (eg.,  average  or  median  value). 

COMMAND  LINE  OPTIONS 
Parameters: 

map  -name  Name  of  an  existing  raster  map  layer  to  be  queried. 

result  =type  Type  of  results  to  be  output. 

Options:  raw,  median,  average 
Default:  raw 

If  raw  results  are  output,  each  of  the  category  '  dues  assigned  to  ceils  falling 
along  the  transect  are  output.  Median  and  average  results  output  a  single  value 
per  transect:  average  outputs  the  average  category  value  of  all  cells  along  the 
transect;  median  outputs  the  median  category  value  of  these  cells. 

line  =east, north, azinunh,distance[, east, north,azimulh,di  stance, . . .] 

A  definition  of  (each)  transect  line,  specified  by  the  geographic  coordinates  of  its 
starting  point  ( easting ,  northing),  the  angle  and  direction  of  its  travel  (azimuth), 
and  its  distance  (distance). 

rhe  azimuth  is  an  argle,  in  degrees,  measured  to  the  east  erf  north.  The  distance 
is  in  map  units  (meters  for  a  metered  database,  like  UTM). 

width  =va/ue  Profile  width,  in  cells  (odd  number). 

Default:  1 

Wider  transects  can  be  specified  by  setting  the  width  to  3,  5,  7,  etc.  The  transects 
are  then  fonned  as  rectangles  3,  5,  7,  etc.,  cells  wide. 

OUTPUT  FORMAT 

The  output  from  this  command  is  printed  to  standard  output  in  ASCII.  The  format  of  the  output  varies 
slightly  depending  on  the  ly|ic  of  result  requested.  The  first  number  printed  is  the  number  of  cells 
associated  with  the  tnuisect.  for  raw  output,  this  number  is  followed  by  the  individual  cell  values.  For 
av  erage  and  median  (Hit put,  this  number  is  followed  by  a  single  value  (i.e.,  the  average  or  the  median 
value). 

Ihc  following  examples  use  the  elevation.dem  raster  map  layer  in  the  spearfish  sample  data  set 
distributed  with  GRASS  4.0.  To  reproduce  these  examples,  first  set  the  geographic  region  as  shown: 

g .region  ra.st=devatioaalem 
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Siqgle-cell  transect: 

r transect  map=el?»aticn.dem  line  =593655,4917280 ,45, 100 

4  1540  1551  1557  1550 


3-cell  wide  transect: 

r .transect  map=eleTatinn.dem  line  =593655,4917280,45,100  width  J 

22  1556  1538  1525  1570  1555  1540  1528  1578  1565  1551  1536  1523  1569  1557  1546 
1533  1559  1550  1542  1552  1543  1548 

(Output  appear;  as  multiple  lines  here,  but  is  really  one  line) 


3-cell  wide  transect  average: 

riransect  map  elevation-dem  line  =593655,4917280,45,100  width  =3 
result  ^average 

22  1548363636 


3-cell  wide  transect  median: 

r .Iran sect  map  elevation-dem  line  =593655,4917280 ,45 ,100  width  3 

result  =median 

22  1549.000000 

NOTES 

This  program  is  a  front-end  to  the  r. profile  program.  It  simply  converts  the  azimuth  and  distance  to  an 
ending  coordinate  and  then  runs  r. profile. 

SEE  ALSO 

r. profile  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.volume  -  Calculates  the  volume  of  data  "clumps,”  and  (optionally)  produces  a  GRASS  site _lists  file 
containing  the  calculated  centroids  of  these  clumps. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.volume 
r.volume  help 

r.volume  [-fq]  dat*=name  [clump=ruj/nc]  [rite_iiat  =name] 

DESCRIPTION 

This  program  computes  the  cubic  volume  of  data  contained  in  user-defined  dumps,  r.volume  outputs: 

(1)  The  category  value  assigned  to  each  clump  formed  by  the  clump  map  layer.  This  value  is  stored 
under  the  "Cat  Number”  column  (field  1)  in  the  output  table. 

(2)  The  average  category  value  of  the  cells  found  in  a  data  map  that  fall  within  the  boundaries  of  each 
clump  in  a  clump  map.  The  table  stores  this  value  under  the  "Average  in  Gump"  column  (fidd  2). 

(3)  The  summed  total  value  of  the  category  values  assigned  to  the  cells  falling  within  each  of  these 
clumps.  This  value  is  output  under  the  "Data  Total"  column  (fidd  3). 

(4)  The  number  of  cells  from  the  data  map  that  fail  within  the  boundaries  of  each  clump  formed  by  the 
clump  map  layer.  This  cell  count  is  stored  under  the  "#  Cells  in  Gump"  column  (fidd  4)  in  the  output 
table. 


(5,6)  The  centroid  (easting  and  northing)  of  each  clump.  These  values  are  output  under  the  "Centroid 
Easting"  and  "Centroid  Northing"  columns  (fidds  5  and  6)  in  the  output. 

(7)  The  total  "volume"  of  each  clump.  For  each  clunp,  die  volume  is  calculated  by  multiplying  the 
area  of  each  cell  by  its  category  value,  and  taking  the  sum  erf  this  value  for  all  cdls  within  the  clump. 
Since,  in  GRASS,  each  cell  in  die  data  map  will  have  the  same  cell  dimensions  (i.e.,  die  same  area), 
this  is  equivalent  to  multiplying  the  area  erf  one  cdl  by  the  "Etata  Total"  column  (fidd  3). 

(The  area  of  each  cdl  is  equal  to  the  product  of  its  east-west  resolution  by  its  north-south  resolution. 
See  g. region.) 

Results  are  sent  to  standard  output  in  the  form  of  a  table.  If  the  user  sets  the  -f  flag,  this  table  will  be 
output  in  a  form  suitable  for  input  to  such  UNIX  programs  as  awk  and  sed\  the  table’s  columns  are 
stored  as  colon- separated  fields.  The  user  can  also  (optionally)  elect  to  store  dump  centroids  in  a 
GRASS  sitejists  file.  A  sample  output  report  is  shown  below. 

r.volume  works  with  the  current  geographic  region  definitions  and  respects  the  current  MASK. 

The  user  can  run  r.volume  non-interactively  by  specifying  parameter  values  on  the  command  line.  If 
the  user  omits  parameter  values  from  the  command  line,  die  program  will  prompt  the  user  for  input 
using  the  standard  interface  described  in  the  manual  entiy  for  parser. 

COMMAND  LINE  OPTIONS 
FIjgK 

-f  Generate  unformatted  output.  Output  is  in  a  form  suitable  for  input  to  UNIX 

programs  like  awk]  each  column  in  the  output  is  separated  by  a  colon.  Results 
are  sent  to  standard  output. 

-q  Run  quietly,  suppressing  the  printing  of  debugging  messages  to  standard  output. 

Parameters: 


data  Rune  of  an  existing  raster  map  layer  containing  the  category  values  to  be 

summed.  The  cell  resolution  (area)  of  the  data  map  will  also  be  used. 

clump  Rune  of  an  existing  raster  map  layer  that  defines  the  boundaries  of  each  clump. 

IVeferably,  this  map  should  lx-  the  output  of  r.clunp.  If  the  user  has  imposed  a 
mask,  the  program  uses  this  mask  as  the  clump  map  layer  if  no  oth<  r  clump  laver 
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is  specified  by  the  user. 

sitejist  The  name  to  be  assigned  to  a  new  GRASS  sitejists  file,  in  which  dump 

centroids  can  be  stored. 

EXAN.  LE  OF  REPORT 

The  following  report  might  be  generated  by  the  command: 

r.voiume  d=devation  c=fiddsunlj  s=flddxtoters 


Cat 

iVerage 

Efata 

#  Cel  1  s 

Centroid 

Total 

Nirber 

in  clinp 

Total 

in  clinp 

Easting 

Northing 

Volune 

1 

1181.09 

75590 

64 

595500.00 

4927700.00 

755900000.00 

2 

1163.50 

69810 

60 

597100.00 

4927700.00 

698100000.00 

3 

1146.83 

34405 

30 

598300.00 

4927700.00 

344050000.00 

4 

1193.20 

366311 

307 

599400.00 

4927300.00 

3663110000.00 

60 

1260.08 

351563 

279 

603100.00 

4921000.00 

3515630000.00 

61 

1213.93 

35204 

29 

603700.00 

4921500.00 

352040000.00 

62 

1207.71 

33816 

28 

604100.00 

4921500.00 

338160000.00 

Total  Volume  =  67226740000.00 


For  ease  of  example,  it  is  assumed  that  each  clump  in  the  fields.ordy  map  layer  is  a  field,  that  cell 
category  values  in  the  elevation  map  layer  represent  actual  elevation  values  in  meters,  and  that  the  data 
base  is  a  UTM  data  base  (in  meters).  This  means  that  field  &  (clump  M)  contains  64  cells;  the 
average  elevation  in  fidd  M.  is  1181.09  meters.  The  sum  of  all  of  the  elevation  values  assigned  to  cells 
within  field  is  75590  meters.  The  volume  (x*y*z)  of  space  in  field  #1  is  equal  to  755900000  cubic 
meters. 

The  'Data  Total"  column  is  the  sum  of  the  cell  category  values  appearing  in  the  elevation  map  layer, 
within  each  field  of  the  fields. only  map  layer.  The  Total  Volume  is  the  sum  multiplied  by  the  e-w 
resolution  times  the  res  resolution. 

CENTROIDS 

The  coordinates  of  the  clump  centroids  are  the  same  as  those  stored  in  the  GRASS  sitejists  file  (if  one 
was  requested).  They  are  guaranteed  to  fall  on  a  cell  of  the  appropriate  category;  thus,  they  are  not 
always  the  true,  mathematical  centroids.  However,  they  will  always  fall  at  a  cell  center. 

FORMAT  OF  SITE  LIST 

For  each  line  of  above  table  the  GRASS  sitejists  file  reads: 

easting )aorthingt^fcat  v=vdume  a=average  t=sum  n=count 

This  can  be  converted  directly  to  a  raster  map  layer  in  which  each  point  is  assigned  to  a  separate 
category. 

APPLICATIONS 

By  preprocessing  the  elevation  map  layer  with  r.mapcalc  and  using  suitable  masking  or  clump  maps, 
very  interesting  applications  can  be  done  with  r.voiume.  For  instance,  one  can  calculate:  the  volume 
of  rock  in  a  potential  quarry;  cut/fill  volumes  for  roads;  and,  water  volumes  in  potential  reservoirs. 
Data  layers  of  other  measures  of  real  values  can  ;ilso  be  used. 


NOTES 

The  output  is  sent  to  the  terminal  screen.  The  user  can  capture  the  output  in  a  file  using  the  UNIX 
redirection  mechanism,  as  in  the  following  example: 

r.voiume  d  data  map  c  clamp  map  s=site_list  >table.out 
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Output  can  also  be  sent  directly  to  the  printer,  as  shown  below: 

r. volume  d  data  map  c=clnmp_map  s=sit* Jlst  |  Ipr 

The  user  should  be  aware  of  what  units  of  measurement  the  cell  e-w  and  n-s  resolution  are  in,  and  in 
what  units  the  data  map’s  cell  category  values  are  stated  (since  these  three  values  will  be  multiplied 
together  to  produce  the  volume). 

This  program  respects  the  current  mask,  and  uses  this  mask  as  the  clump  map  layer  if  none  is  specified 
by  the  user. 

SEE  ALSO 

g.region,  r. clump,  rmapcalc,  rjnask,  s.db.rim,  sjnenu  and  parser 
AUTHOR 

Dr.  James  Hnthome,  Central  Washington  University  CHS  Laboratory 
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NAME 

r.watershed  -  Watershed  basin  analysis  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.watershed 
r.watershed  help 

r.watershed  [-tn4]  elevation  =name  {depression -name)  (flow  =name] 

[disturbed  Jand  juinx (value!  [blocking -  name]  [threshold-  value]  [max .slope .length  value] 
[accumulation -name. ]  [drainage  name]  [basin  =name}  [stream  =name\ 

[half. basin  name]  [visual  =name]  [length-slope  name]  [ .slope.steepness  =name j  [armsed  -name] 
DESCRIPTION 

r.watershed  generates  a  set  of  maps  indicating:  1)  the  location  of  watershed  basins,  2)  information  to 
interface  with  ARMSED,  a  storm- water  runoff  and  sedimentation  yield  model,  and  3)  the  IS  and  S 
factors  of  the  Revised  Universal  Soil  Loss  Equation  (RUSLF.). 

r.watershed  can  be  run  either  interactively  or  non- interactively.  If  the  user  types 

r.wai :  ■  .  ."i 

on  the  command  line  without  program  arguments,  the  program  will  prompt  the  user  with  a  verbose 
description  of  the  input  maps.  The  interactive  version  of  r.watershed  can  prepare  inputs  to  lumped- 
parameter  hydrologic  m<xlels.  After  a  verbose  interactive  session,  r.watershed  will  query  the  user  for  a 
number  of  map  layers.  Each  map  layer's  values  will  be  tabulated  by  watershed  basin  and  sent  to  an 
output  file.  This  output  file  is  organized  to  ease  data  entry  into  a  lumped-parameter  hydrologic  model 
program.  The  non  interactive  version  of  r.watershed  cannot  create  this  file. 

The  user  can  run  the  program  non- interactively,  by  specifying  input  map  names  on  the  command  line. 
Parameter  names  may  be  specified  by  their  full  names,  or  by  any  initial  string  that  distinguish  them 
from  other  parameter  names.  In  r. watershed's  case,  the  first  two  letters  of  each  name  sufficiently 
distinguishes  parameter  names.  For  example,  the  two  expressions  below  are  equivalent  inputs  to 
r.watershed : 

r.watershed  el  elevanap  th  =100  at  =stream  jnap  bn  basin  on  up 

r.watershed  elevation  =eJev.map  threshold  =100  stream  -  stream  Jnap  basin  =basuunap 

OPTIONS 

-to  Without  this  flag  set,  the  entire  analysis  is  run  in  memory  maintained  by  the  operating  system. 
This  can  be  limiting,  but  is  relatively  fast.  Setting  the  flag  causes  the  program  to  manage 
memory  on  disk  which  allows  larger  maps  to  be  processed  but  is  considerably  slower. 

-4  Allow  only  horizontal  and  vertical  flow  of  water.  Stream  and  slope  lengths  are  approximately 
the  same  as  outputs  from  default  surface  flow  (allows  horizontal,  vertical,  and  diagonal  flow  of 
water).  This  flag  will  also  make  the  drainage  basins  look  more  homogeneous. 

elevation 

Input  map:  Elevation  on  which  entire  analysis  is  based. 
depression 

Input  map:  Map  layer  of  actual  depressions  in  the  landscape  that  are  large  enough  to  slow  and 
store  surface  runoff  from  a  storm  event.  Any  non  zero  values  indicate  depressions. 

flow  Input  map:  amount  of  rrverlarxl  flow  per  cell.  This  map  indicates  the  amount  of  overland  flow 
units  that  each  cell  will  contriUite  to  the  watershed  basin  model.  Overland  flow  units  represent 
the  amount  of  overland  flow  each  ceil  contributes  to  surface  flow.  If  omitted,  a  value  of  one 
(1)  is  assumed. 

disturhedJand 

Raster  map  input  layer  or  value  containing  the  percent  of  di studied  land  (i.e..  croplands,  and 
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construction  sites)  where  the  raster  or  input  value  of  17  equals  17%.  If  no  map  or  value  is 
given,  r.watershed  assumes  no  disturbed  land  Ibis  input  is  used  for  the  RUSLE  calculations. 

blocking 

Input  map:  terrain  that  will  Hock  overland  surface  flow.  Terrain  that  will  Hock  overland 
surface  flow  and  restart  the  slope  length  for  the  RUSLE.  Any  non-zero  values  indicate 
Hocking  terrain. 

threshold 

The  minimum  size  of  an  exterior  watershed  basin  in  cells,  or  overland  flow  units. 
max -slope. length 

Input  value  indicating  the  maximum  length  of  overland  surface  flow  in  meters.  If  overland 
flow  travels  greater  than  the  ximum  length,  the  program  assumes  the  maximum  length  (it 
assumes  that  landscape  characteristics  not  discemaHe  in  the  digital  elevation  model  exist  that 
maximize  the  slope  length).  This  input  is  used  for  the  RUSLE  calculations  and  is  a  sensitive 
parameter. 

accumulation 

Output  map:  number  of  cells  that  drain  through  each  cell.  The  absolute  value  of  each  cell  in 
this  output  map  layer  is  the  amount  of  overland  flow  that  traverses  the  cell.  Ibis  value  will  be 
the  number  of  upland  cells  plus  one  if  no  overland  flow  map  is  given.  If  the  overland  flow 
map  is  given,  the  value  will  be  in  overland  flow  units.  Negative  numbers  indicate  that  those 
cells  possiHy  have  surface  runoff  from  outside  of  the  current  geographic  region.  Thus,  any 
cells  with  negative  values  cannot  have  their  surface  runoff  and  sedimentation  yields  calculated 
accurately. 

drainage 

Qitput  map:  drainage  direction.  Provides  the  "aspect”  for  each  cell.  Multiplying  positive 
values  by  45  will  give  the  direction  in  degrees  that  the  surface  runoff  will  travel  from  that  cell. 
The  value  -1  indicates  that  the  cell  is  a  depression  area  (defined  by  the  depression  input  map). 
Other  negative  values  indicate  that  surface  runoff  is  leaving  the  boundaries  of  the  current 
geographic  region.  The  absolute  value  of  these  negative  cells  indicates  the  direction  of  flow. 

basin  Qitput  map:  Unique  label  for  each  watershed  basin.  Each  basin  will  be  given  a  unique 
positive  even  integer.  Areas  along  edges  may  not  be  large  enough  to  create  an  exterior 
watershed  basin.  0  values  indicate  that  the  cell  is  not  part  of  a  complete  watershed  basin  in 
the  current  geographic  region. 

stream  Output  map:  stream  segments.  Values  correspond  to  the  watershed  basin  values. 
half. basin 

Qitput  map:  each  half-basin  is  given  a  unique  value.  Watershed  basins  are  divided  into  left 
and  right  sides.  The  right-hand  side  cells  of  the  watershed  basin  (looking  upstream)  are  given 
even  values  corresponding  to  the  watershed  basin  values.  The  left-hand  side  cells  of  the 
watershed  basin  are  given  odd  values  which  are  one  less  than  the  value  of  the  watershed  basin. 

visual  Qitput  map:  useful  for  visual  display  of  results.  Surface  runoff  accumulation  with  the  values 
modified  to  provide  for  easy  display.  All  negative  acciuixilation  values  are  changed  to  zero. 
All  positive  values  above  the  basin  threshold  are  given  the  value  of  the  basin  threshold. 

length. si  ope 

Qitput  map:  slope  length  and  steepness  (US)  factor.  Contains  the  factor  for  the  Revised 
Universal  Soil  I/>ss  Equation.  Equations  taken  from  Revised  Universal  Soil  Loss  Equation 
for  Western  Rangelands  (see  SEE  ALSO  section).  Since  the  US  factor  is  a  small  number,  it 
is  multiplied  by  100  for  the  GRASS  output  map. 

slope  steepness 

Qitput  map:  slope  steepness  (S)  factor  for  RUSLE..  Contains  the  rev  ised  S  factor  for  the 
Universal  Soil  Uiss  Equation.  Equations  taken  fn>m  aitiele  entitled  Revised  Slope  Steepness 
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Factor  for  the  Universal  Soil  Loss  Equation  (see  SEE  ALSO  section).  Since  the  S  factor  is 
a  small  number  (usually  less  than  one),  it  is  multiplied  by  100  for  the  GRASS  output  map 
layer. 

armsed  Output  file:  Useful  as  input  to  r. grass  armsed.  ASGI  file  output  that  can  be  fed  into  the 
r. grass. armsed  program  to  help  calculate  sedimentation  yields  and  unit  hydro-graphs.  As  of 
01/17^)1,  this  option  had  not  yet  been  fully  tested. 

NOTES 

There  are  two  versions  of  this  program:  ram  and  seg.  Which  is  run  by  r.watershed  depends  on 
whether  the  -m  flag  is  set.  ram  uses  virtual  memory  managed  by  the  operating  system  to  store  all  the 
data  structures  and  is  faster  than  seg\  seg  uses  the  GRASS  segment  library  which  manages  data  in  disk 
files,  seg  allows  other  processes  to  operate  on  the  same  CPU,  even  when  the  current  geographic  region 
is  huge.  Due  to  memory  requirements  of  both  programs,  it  will  be  quite  easy  to  run  out  of  memory.  If 
ram  runs  out  of  memory  and  the  resolution  size  of  the  current  geographic  region  cannot  be  increased, 
either  mote  memory  needs  to  be  added  to  the  computer,  or  the  swap  space  size  needs  to  be  increased. 
If  seg  runs  out  of  memory,  additional  disk  space  needs  to  be  freed  up  for  the  program  to  run. 

T 

seg  uses  the  A  least-cost  search  algorithm  to  determine  the  flow  of  water  over  the  landscape  (see  SEE 
ALSO  section).  The  algorithm  produces  results  similar  to  those  obtained  when  running  r.cost  and 
r. drain  on  every  cell  on  the  map. 

In  many  situations,  the  elevation  data  will  be  too  finely  detailed  for  the  amount  of  time  or  memory 
available.  Running  r.watershed  will  require  use  of  a  coarser  resolution.  To  make  the  results  more 
closely  resemble  the  finer  terrain  data,  create  a  map  layer  containing  the  lowest  elevation  values  at  the 
coarser  resolution.  This  is  done  by:  1)  Setting  the  current  geographic  region  equal  to  the  elevation  map 
layer,  and  2)  Using  the  neighborhood  command  to  find  the  lowest  value  for  an  area  equal  in  size  to 
the  desired  resolution.  For  example,  if  the  resolution  of  the  elevation  data  is  30  meters  and  the 
resolution  of  the  geographic  region  for  r.watershed  will  be  90  meters:  use  the  minimum  function  for  a 
3  by  3  neighborhood.  After  going  to  the  resolution  at  which  r.watershed  will  be  run,  r.watershed  will 
be  taking  values  from  the  neighborhood  output  map  layer  that  represents  the  minimiun  elevation 
within  the  region  of  the  coarser  cell. 

The  minimum  size  of  drainage  basins  is  only  relevant  for  those  basins  that  have  no  basins  draining  into 
them  (they  are  called  exterior  basins).  An  interior  drainage  basin  has  the  area  that  flows  into  an  interior 
stream  segment.  Thus,  interior  drainage  basins  can  be  of  any  size. 

The  r.watershed  program  does  not  require  the  user  to  have  the  current  geographic  region  filled  with 
elevation  values.  Areas  without  elevation  data  MUST  be  masked  out  using  the  rmask  command. 
Areas  masked  out  will  be  treated  as  if  they  are  off  the  edge  of  the  region.  Masks  will  reduce  the 
memory  necessary  to  run  the  program.  Masking  out  unimportant  areas  can  significantly  reduce 
processing  time  if  the  watersheds  of  interest  occupies  a  small  percentage  of  the  overall  area. 

Zero  data  values  will  be  treated  as  elevation  data  (not  no_data).  If  there  are  zero  data  along  the  edges 
cf  the  current  region,  that  edge  will  not  be  able  to  propagate  negative  accumulation  data  to  the  rest  of 
the  map.  This  might  give  users  a  false  sense  of  security  about  the  quality  of  their  data.  If  there  are 
incomplete  data  in  the  elevation  map  layer,  users  should  mask  out  those  areas. 


SEE  ALSO  _ 

T 

The  A  least-cost  search  algorithm  used  by  r.watershed  is  described  in  "Using  the  A  Seiirch 
Algorithm  to  Develop  Hydrologic  Models  from  Digital  Elevation  Duta,"  in  Proceedings  of 
International  Geographic  Information  Systems  (IGIS)  Symposium  '89,  pp  275-2S1  (Baltimore,  MD, 
18-19  March  1989),  fcy  Charles  Ehlschlaeger,  US.  Army  Construction  Engineering  Research 
Laboratory . 
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length  slope  and  steepness  {length-slope)  factor  equations  were  taken  from  "Revised  Universal  Soil 
lews  Equation  for  Western  Rangelands presented  at  the  U.S-A/Mexico  Symposium  of  Strategies  for 
Classification  and  Management  of  Native  Vegetation  for  Food  Production  In  Arid  Zones  (Tucson, 
AZ,  12-16  Oct  1987),  by  M.  A  Wdtz,  K.  G.  Renard,  and  J.  R.  Simanton. 

The  slope  steepness  (slope steepness)  factor  contains  the  revised  slope  steepness  factor  for  the 
Universal  Soil  Loss  Equation.  Equations  were  taken  from  article  entitled  "Revised  Slope  Steepness 
Factor  for  the  Universal  Soil  Loss  Equation,"  in  Transactions  of  the  ASAE  (Vol  30(5),  Sept-Qct 
1987),  by  Me  Cod  et  al. 

r.cost,  r. drain,  r. grass. armed  rjnask 

AUTHOR 

Charles  Ehlschlaeger,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.weight  -  Raster  map  overlay  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.wdght 
r.weight  bdp 

r.wdght  output  =name  [action  =namt]  [color  =name]  [title  =’ name"] 


COMMAND  LINE  OPTIONS 

Name  of  the  output  raster  map  layer  created. 

Specifies  which  mathematical  operation  (addition  or  multiplication)  is  to  be  used 
to  calculate  weights. 

Options:  add,  mult 
Default:  add 

Type  of  color  table  to  be  assigned  to  the  output  raster  map  layer  created 
Options:  grey,  wave,  ramp 
Default:  grey 

A  tide  to  be  assigned  to  the  output  map  layer  created.  If  this  title  contains  more 
than  one  word,  it  should  be  quoted. 

Default:  (none) 

DESCRIPTION 

r.weight  is  a  language  driven  raster  map  overlay  program.  It  provides  a  means  for  performing 
geographical  analyses  using  several  raster  maps,  r.weight  asks  the  user  to  weight  (assign  numeric 
values  to)  the  raster  map  categories  of  interest.  The  assignment  of  weighted  values  requires  that  the 
user  intimately  understand  the  analysis  being  undertaken.  How  important  is  the  slope  of  the  land  in 
comparison  with  the  current  land  use,  or  the  depth  to  bedrock?  The  assignment  of  values  to  the  land’s 
characteristics  allows  r.weight  to  mix  and  compare  apples  and  oranges,  such  as  slopes  and  land  uses, 
and  soil  types  and  vegetation. 

r.weight  is  a  language-driven  analysis  tod.  It  responds  to  worded  commands  typed  at  the  terminal. 
Lfelp  is  always  available  via  the  one  word  command:  help.  Commands  available  in  r.weight  are  listed 
below. 


Parameters: 
output  =name 
action  =name 


color  =name 

title— "name" 


Note  that  raster  map  names  appear  in  parentheses.  The  use  of  parentheses  is  now  optional  in  r.weight. 


list  maps 

list  categories  (name) 

list  save 

list  analysis 

print  analysis 

choose  (name) 

assign  (name) 

assign  (name)  (cat)  (val) 

assign  (name)  (cat)  (cat)  (val) 


List  available  raster  maps 

List  categories  for  raster  map  (name) 

List  saved  analyses 

Display  current  analysis  request 

Send  current  analysis  request  to  printer 

Choose  raster  map  (name)  for  analysis 

Interactive  way  to  assign  weights  for  raster  map  (name) 

Assign  weight  (val)  to  category  (cat)  for  raster  map  (name) 


Assign  weight  (val)  to  categories  (cat)  (cat)  for  raster  map  (name) 


save 


Save  the  current  analysis 
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recover 

Recover  old  analysis 

add 

mult 

Request  that  weights  be  added  (tins  is  the  default) 

Request  that  weights  be  multiplied 

execute 

Run  analysis 

erase 

Erase  the  screen 

color  grey 

color  wave 

color  ramp 
quit 

Set  the  graphics  monitor  colors  to  a  grey  scale  (this  is  the  default) 
Set  the  graphics  monitor  colors  to  a  color  wave. 

Set  the  graphics  monitor  colors  to  a  color  ramp. 

Leave  r.weight 

A  more  detailed  explanation  of  a  command  can  be  obtained  by  typing: 

help  (command) 

SUGGESTED  APPROACH 

In  order  for  r.weight  to  generate  raster  maps  useful  for  analysis,  the  user  must  make  a  reasonable  and 
defensible  request.  While  much  more  powerful  than  r. combine,  r.weight  is  also  more  dangerous.  The 
user  provides  the  necessary  value  judgements,  which  are  registered  as  weights.  Only  well-conceived 
value  judgements  will  result  in  defensible  results.  We  suggest  the  following  approach  to  a  weighted 
overlay  analysis: 

SIEP  1:  BEFORE  RUNNING  WEIGHT 

a)  Define  the  question  to  be  answered,  eg.,  "Locate 
sites  suitable  for  building  apartments." 

b)  Determine  what  mapped  information  is  useful  for 
answering  the  question,  eg.,  geology,  soils, 
land_use,  floocLpotential. 

c)  Based  on  professional  judgement,  statistical 
inference,  and  engineering  principals,  assign 
weights  to  the  categories  in  the  chosen  raster  maps. 

STEP  2:  CHOOSE  CELL  MAI’S 

In  r.weight,  use  the  command  choose  to  identify 
up  to  six  raster  maps  of  interest. 

STEP  3:  ASSIGN  WEIGHTS 

Using  the  r.weight  command  assign,  assign 
specific  weights  to  raster  map  categories. 

STEP  4:  SAVE  ANALYSIS 

Use  the  save  command  to  save  a  cop)'  of  the  analysis 
requested  for  later  use. 

STEP  5:  RUN  ANALYSIS 

Use  execute  to  run  the  analysis. 

STEP  6:  EVALUATE  RESUI  TS 

To  modify  an  existing  aivilysis  request,  use  the  recover 
command  to  retrieve  the  analysis  and  then  go  to  STEP  3. 
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SEE  ALSO 

GRASS  Tutorial:  r.wdght 

r. infer,  r. combine,  rjnapcalc. 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r. weight. new  -  Weighted  overlay  raster  map  layer  analysis  program. 

(GRASS  Raster  Program) 

SYNOPSIS 

r.weightjiew  [output]  [action]  [color] 

r.weightjiew  [output  =op/ion]  [action  =option\  [color  =option] 

DESCRIPTION 

r. weight. new  is  the  non- interactive  version  of  r. weight.  Both  programs  allow  the  user  to  assign 
numeric  values  (i.e.,  "weights")  to  individual  category  values  within  raster  map  layers.  These  weights 
are  then  distributed  locaiionally  throughout  a  raster  map  layer  based  cm  the  distribution  of  the  categories 
with  which  they  are  associated.  The  user  can  weight  the  categories  of  several  raster  map  layers  in  a 
data  base.  Such  weighted  raster  map  layers  can  then  be  overlaid,  r.weightjiew  will  combine  weights 
in  the  overlaid  map  layers  by  cell  location. 

A  resulting  output  raster  map  layer  depicts  the  combination  of  map  layer  weights  across  a  landscape. 
These  values  represent  a  hierarchy  of  suitability  for  some  user-defined  purpose.  To  obtain  a  more 
detailed  description,  see  die  manual  entry  for  r. weight. 

Output  raster  map  must  be  specified  (no  default) 

Action  must  be  either  (add  or  mult)  (default:  add) 

Color  table  for  the  new  raster  map  (grey  ]  wave  |  ramp)  (default:  grey) 

dice  the  r.weightjiew  command  line  is  entered,  the  user  will  need  to  enter  a  raster  map  layer  name 
and  assign  numeric  values  to  its  categories.  Values  can  be  assigned  to  the  categories  erf  up  to  six  raster 
map  layers  within  r.weight.rtew  in  a  single  analysis.  Help  is  available  to  the  user  by  typing 

r.weightjiew  help. 

EXAMPLE 

The  following  is  the  format  in  which  data  should  be  entered  to  r.weightjiew : 

Rasterjayerl 
[Reclass  rule  la] 

[Reclass  rule  lb] 

Raster J  ay  er2 
[Reclass  rule  2a] 
etc. 
end 

Rasterjayer.  raster  jmap  OR  "raster _jnap  in  mapset ” 

Reclass  mle:  (example)  1=5  OR  20  thru  50  =  10  (must  leave  spaces  between 
the  category,  =,  and  value  entries) 

Example:  (the  prompts  are  shown  in  bold) 

>  r.weight.new  sites  add  wave 

>  soils 


soils>  1  thru  20  =  5 
soils>  21  thru  30  =  10 
soils>  landcover 

landcover  >  1=2 
landcover  >  2  =  4 
landcover >  3  thru  8=6 
landcover>  end 
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NOTES 

The  user  must  be  knowledgeable  about  r.weight  to  run  r: weight. new.  r. weight  Jiew  does  not  provide 
the  user  with  a  listing  of  raster  map  layers  or  map  layer  categories.  Users  unsure  about  raster  map 
layer  names  should  run  the  GRASS  program  g.list.  To  obtain  a  listing  of  the  categories  fa-  a  raster 
map  layer  run  r. report. 

The  user  can  create  an  input  file  containing  the  data  needed  to  run  r.weight Jiew.  This  file  muat  list  the 
raster  map  layer  and  reclass  rules  in  the  format  shown  in  the  above  example.  The  prompts  must  not  be 
included  in  the  file.  This  file  can  be  directed  into  r.weight.new  at  the  command  line  by  typing 

r.weightjiew  output  action  color  <  input.filc 

This  program  remains  under  alpha  testing.  It  resides  in  the  src alpha  directory  and  must  be  compiled 
separately  by  the  user. 

BUGS 

When  entering  data  fa  the  reclass  rules,  if  the  user  does  not  include  spaces  between  the  category,  =, 
and  value,  the  program  will  assume  that  the  entry  is  a  raster  map  layer. 

SEE  ALSO 

g.list,  r. combine,  r Safer,  r. report  r.weight 

AUTHOR 

Ehvid  (jerries,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

r.what  -  Qjeries  raster  map  layers  on  their  category  values  and  category  labels. 

( GRASS  Raster  Program) 

SYNOPSIS 

r.what 
r.what  help 

r.what  [-f]  input  =name\  /tame ,...] 

r.what  [-f]  input  =name[ /tame, ...]  [ < inputfile] 

DESCRIPTION 

r.what  outputs  the  category  values  and  (optionally)  the  category  labels  associated  with  user-specified 
locations  on  raster  input  map(.s).  Locations  are  specified  as  geographic  x,y  coordinate  pairs  (i.e.,  pair  of 
eastings  and  northings);  the  user  can  also  (optionally)  associate  a  label  with  each  location. 

'Ihe  program  will  lx-  run  non-interactively  if  the  user  specifies  the  program  parameter  values  and 
(optionally)  the  flag  setting  on  the  command  line,  using  the  form: 

r.what  [ -f]  input  =name[/iame ,...] 

where  each  input  name  is  the  name  of  a  raster  map  layer  whose  category  values  are  to  be  queried,  and 
the  (optional)  flag  -/  directs  r.what  to  also  output  category  labels.  The  user  can  also  redirect  a  user- 
created  ASCII  input  file  containing  a  list  of  geographic  coordinate  pairs  and  (optionally)  user-named 
labels,  into  r.what  using  the  form: 

r.what  [-f]  input  name\/iame [  <  input  file] 

If  the  user  does  not  redirect  an  input  file  containing  these  coordinates  into  the  program,  the  program 
will  query  the  user  for  point  locations  and  labels. 

Alternately,  the  user  can  simply  type: 

r.what 

on  tlx  command  line,  without  program  arguments.  In  this  case,  the  user  will  be  prompted  for  the  flag 
sotting  ;uk1  parameter  values  using  the  standard  GRASS  parser  interface  described  in  the  manual  entry 
for  parser. 

Flag: 

-f  Also  output  the  category  label(s)  associated  with  the  cell(s)  at  the  user-specified 

location(s). 


Parameters: 


input  =mame\, name, name,...} 

Ihe  name(s)  of  one  or  more  existing  raster  map  layers  to  be  queried. 


EXAMPLES 

I  ho  contents  of  the  ASCII  inputfile  to  r.what  can  be  typed  in  at  the  keyboard,  redirected  front  a  file, 
or  pqxxl  from  am  alter  program  (like  d.where).  Each  line  of  the  input  consists  of  an  easting,  a  northing, 
;utd  ;tn  optional  label,  which  are  separated  by  spaces.  Ilte  word  end  is  type*. I  to  end  input  of 
coordinates  to  r.what.  Ibr  example: 

635342.21  7654321.09  site  1 
653324.88  7563412.42  site  2 
end 


r.what  output  consists  of  the  input  geographic  location  ami  laltel,  and,  for  each  user  named  raster  map 
layer,  tlx  category’  value,  and  (if  -/  is  s(xcifiod)  the  category  label  assort  ated  with  the  cel  I  <  C  at  this 
geographic  fixation.  Sample  iiqxit  (in  W>ld)  to;tnd  ixitpul  (in  plain  text)  from  r.what  re  given  Ixlow. 
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r.what  input  =so»ls^apect 
635342.21  7654321.09  site  I 

653324.88  7563412.42  site  2 
end 

63534221 17654321.09  |site  1 145  j21 

653324.88  |7563412.42  jsite  2  |44  (20 


r.what  -f  input  =soil suspect 
635342.21  7654321.09  site  1 

653324.88  7563412.42  site  2 
end 

63534221 17654321.09  (site  1 145  )NaC|21 130  degrees  NW 

653324.88  (7563412.42  jsite  2  j44  jNdC  |20  (15  degrees  NW 

NOTES 

The  maximum  number  of  raster  map  layers  that  can  be  queried  at  one  time  is  14. 
SEE  ALSO 

d.sites,  d.where,  r.cats,  r. report,  ratals,  sites,  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

s.db.rim  -  RIM  data  base  management/query  interface  for  GRASS  sites  data. 

( GRASS  Sites  Management  Program) 

SYNOPSIS 

s.dbj*im 

s.dbxim  data-base 
DESCRIPTION 

s.db.rim  allows  users  to  create,  manage  and  query  information  about  site  locations  (sites)  across  the 
landscape.  Required  inputs  can  be  entered  interactively,  or  from  the  command  line.  Command  line 
input  may  be  entered  through  a  prepared  text  file  or  from  the  keyboard  (standard  input).  The  s.db.rim 
command  language  is  defined  in  section  one.  The  menu-driven  interactive  version  is  described  in 
section  two. 

These  programs  are  actually  a  marriage  of  the  GRASS  environment  and  the  programmer’s  interface 
library  of  the  relational  data  base  management  program  RIM,  distributed  publically  by  the  University  of 
Washington  Academic  Computing  Sendees  as  FORTRAN  77  code.  Your  system  must  have  a 
IORTRAN  77  compiler  to  use  s.db.rim. 

SECTION  ONE  -  THE  COMMAND  VERSION 

The  command  line  driven  version  of  s.db.rim  is  run  by  typing  the  below  command,  where  datajbase 
is  the  name  of  an  existing  RIM  sites  data  base: 

s.dbj-im  data  base 

The  sites  data  bases  are  stored  in  a  subdirectory  named  ’rim/sites’  in  the  user’s  current  mapset.  Data 
bases  in  other  mapsets,  selectable  through  the  GRASS  g.mapsets  command,  can  be  accessed  for  ’read¬ 
only’  retrieval  of  records.  Each  mapset  may  have  many  data  bases.  Each  data  base  within  a  mapset 
must  liavc  a  different  name;  user-supplied  names  for  data  bases  are  limited  to  seven  (7)  characters  in 
order  to  maintain  compatibility  with  the  standard  version  of  RIM.  As  with  other  GRASS  commands, 
mapsets  are  searched  in  the  mapset  SEARQ  L  P  ATI  I  order  when  a  data  base  needs  to  be  opened. 

Each  site  data  base  is  composed  of  multi-field  records  (rows  or  tuples,  in  DBMS  jargon).  Each  field 
and  its  position  in  the  site  form  is  defined  via  input  to  the  .make  command  when  a  data  base  is 
originally  defined.  It  is  possible  to  add  new  fields  or  change  the  length  of  existing  fields  after  data  has 
been  loaded;  however,  this  is  not  straightforward  and  is  not  described  here;  deleting  of  fields  is  also 
possible,  but  requires  even  more  experience  and  knowledge  The  user  needs  to  carefully  design  the 
data  base  fields  and  form  (layout)  and  check  the  operation  w  ith  r  few  pieces  of  test  data  before  loading 
data  for  a  large  number  of  sites. 

COMMANDS 

(Note:  For  each  of  the  "dot  commands,"  eg.,  .make,  described  below  there  is  a  menu  choice  to  select 
when  nmning  the  interactive  version.  Ihe  interactive  menus  are  described  in  section  two  of  this 
ckx  ument.  Some  display  capabilities  exist  in  the  interactive  version  which  are  not  directly  implemented 
in  the  command  version.) 

The  commands  are  given  alpliabeticallv  here  for  easy  reference.  The  make  command  is  required  to 
create  a  data  base  and,  therefore,  will  be  the  first  to  lx:  entered  by  a  new  user.  Abbreviations  down  to 
the  string  shown  in  (  )  arc  accepted;  this  is  primarily  for  those  giving  s.db.rim  commands  from  a 
terminal,  but  abbreviations  may  also  be  used  in  batch  files. 

Each  command  is  intnxluced  w  ith  an  injxit  record  (line)  which  starts  with  a  periixl  and  is  followed  by 
one  ol  the  words  shown  lx:low;  for  some  commands  the  command  line  also  contains  one  or  nxire 
required  or  optional  parameters.  Additional  or  optional  input  instructions/data  for  a  cominuxl  are 
supplied  on  successiv  e  lines;  a  .end  line  is  needed  by  some  commands  to  signify  the  end  of  these  input 
lines. 
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Alphabetical  Command  Summary 


tconwnand 

This  is  the  only  s.db.rim  command  not  starting  with  a  period,  "command"  is  a  single  shell 
command  line  which  is  executed  by  a  "G_systemO"  call  (see  GRASS  gis  library).  Many 
UNIX  utilities  (eg.,  vi,  Is,  print)  and  most  GRASS  commands  (e.g.,  d.rast,  d.points,  g.list, 
g.region,  d.zoom,  rjnask)  may  be  executed.  It  is  permitted,  and  often  useful,  to  change 
"region"  and  "MASK"  wi'hin  s.db.rim.  Multiple  commands  may  be  separated  by  in  the 
standard  UNIX  way.  Note  that  a  "led  directory;  Is"  will  chaise  to  the  specified  directory  and 
list  files,  but  the  effective  working  directory  for  s.db.rim  will  not  be  changed  when  the 
command  terminates. 

.add  (xi) 

Add  a  new  site  record  (row)  to  the  open  data  base.  Each  line  following  contains  a  field  name 
followed  by  spaces  and/or  tabs,  then  the  value  or  character  string  to  store  for  that  field.  Field 
information  lines  end  with  .end.  Some  fields  may  be  absent  and  fields  may  appear  in  anv 
order.  Checks  are  made  for  the  input  of  data  for  the  one  required  field  (site  number),  for  string 
length  for  string  type  fields,  and  for  duplicate  site  numbers.  If  split  fields  are  used  in  the  data 
base  layout  (see  make),  text  data  for  each  split  field  must  be  added  as  a  separate  line.  If  there 
are  any  problems,  the  record  will  not  be  stored  and  a  message  will  be  output.  This  format 
makes  it  relatively  easy  to  import  data  from  most  other  DBMS.  The  ".print  -a"  command,  see 
below,  outputs  data  in  this  list  format. 


Example: 

add 

site_id  204 
north  469067330 
east  601410.00 
reference  Jones  (1987) 

.end 

.backup  (.b)  file_name 

The  .backup  command  is  used  to  dump  the  entire  data  base  from  the  RIM  binary  files  to  a  text 
file  format  (see  UNLOAD  in  the  RIM  User5  s  Manual).  The  file_name  can  be  a  relative  path 
name  or  full  path  name.  The  file  will  contain  the  data  base  definition,  screen  layout 
information,  and  tabular  data.  This  text  file  is  transportable  to  RIM  or  s.db.rim  running  on 
any  other  computer;  it  may  also  be  reloaded  to  recreate  the  s.db.rim  data  base.  A  message 
will  be  output  if  there  is  any  problem  writing  the  .backup  file.  Backup  can  only  be  done  on 
data  bases  in  the  user’s  current  mapset. 

To  reload  your  data  base  from  the  backup  file  (normally  not  necessary): 


GRASS  4>cd  $LOCATIQNAim/rites 
GRASS  4>rm  db_namerimdbl 
GRASS  4>rm  db_namerimdb2 
GRASS  4>rm  db_namerimdb3 
GRASS  4>rim 
RIM> input  "path/file" 

RIM>exit 


# right  directory 

#  remove  data  base  (or  mv  to  somewhere) 

#  remove  data  base  (or  mv  to  somewhere) 

#  remove  data  base  (or  mv  to  somewhere) 

#  run  RIM  manually 

#RIM  rebuilds  data  base  from  data 
written  by  .backup 


.change  (.c)  [  -l  ] 

Without  the  1"  flag,  each  line  following  change  is  in  the  same  format  as  for  the  add 
command.  The  site  number  field  is  required  and  the  site  number  must  match  an  existing  site  in 
the  data  base.  Only  those  fields  for  which  lines  are  provided  are  changed  in  the  record.  After 
the  .end  the  changed  record  is  stored,  if  all  is  ok;  otherwise,  a  message  is  output. 
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If  the  "1"  flag  (for  "list")  is  given,  the  site  number  field  is  omitted  and  the  specified  field 
values  are  changed  for  all  sites  currently  selected  by  .find  and/or  .query. 

.delete  (.d) 

This  command  is  used  to  delete  data  records  for  sites.  Deletion  of  sites  is  permanent.  A 
backup  of  the  data  base,  or  copies  of  the  data  base  files,  are  the  ways  to  protect  your  valuable 
data. 

The  lines  following  the  .delete  command  should  contain  only  the  ate  numbers,  with  a  .end  line  being 
last. 

The  following  command  sequence  will  delete  all  the  sites  currently  on  die  internal  site  fist  (the  result  of 
the  last  .query  or  .find  command)  after  asking  for  approval. 

.delete 

.end 

.end  (.e) 

Ends  multi-line  input  for  several  other  commands. 

.exit  (.ex) 

Use  .exit  to  end  operation  of  s.db.rim  cleanly.  In  general,  do  not  use  CTRDC  to  exit  unless 
absolutely  necessary.  When  .exit  is  encountered  in  a  batch  file,  input  will  revert  back  to  the 
previous  file,  or  the  terminal,  if  arty,  that  called  the  batch  file. 

.find  (.f)  [  a  |  -d  ]  {  -m  ]  [  -w  ] 

The  .find  command  is  used  to  find  the  site(s)  closest  to  a  given  point  (the  target).  The  target 
can  be  defined  in  one  of  several  ways.  The  found  sites  are  stored  on  an  internal  sites  list  for 
output  bv  other  commands;  however,  see  note  2,  below.  The  found  sites  are  stored  on  the 
interred  sites  list  in  order  of  proximity  to  the  target  location. 

The  optional  .find  command  line  parameter  specifies  the  current  MASK  (m),  if  any,  or  the 
current  region  ( w),  as  a  filter  on  the  retrieved  sites,  -m  automatically  implies  -w,  as  the 
MASK  is  not  defined  outside  the  current  region.  If  the  -a  flag  is  given,  the  retrieved  sites  will 
be  appended  to  those  previously  retrieved  with  a  .query  or  .find;  duplicates  will  be 
automatically  discarded.  The  -d  flag  causes  the  retrieved  sites  to  be  deleted  from  the  internal 
site  list,  if  present  there.  Very  complex  selections  can  be  done  by  interspersing  appends  and 
deletes  to  arrive  at  a  final  list  of  sites.  For  instance,  selecting  those  sites  within  2000  meters  of 
a  target  and  then  deleting  those  within  1500  meteres  of  the  target  will  give  a  final  list  of  those 
from  1500  to  2000  meters. 

The  single  required  line  following  the  .find  line  gives  the  program  the  necessary  target 
information.  The  following  examples  show  the  possibilities. 

find> 602793.90  4379010.00 

will  find  the  one  site  nearest  these  coordinates  and  store  it  on  the  internal  site  list. 
find>619840  4599000  10 

will  find  the  10  sites  (or  fewer,  if  there  are  not  that  many)  closest  to  the  given  location. 
find>sitc  132  10 

will  find  tire  10  sites  closest  to  the  location  of  site  132  in  the  data  base  (including  site  132).  If 
site  132  does  not  exist,  no  action  is  taken. 
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find>  distance  from  472910X16  5732001.0  5000 
will  find  all  sites  within  5000  (meters,  in  UTM  coordinates)  of  the  target  location. 
find>  distance  from  site  16  -2500 

will  find  all  sites  greater  than  2500  (meters)  from  the  location  of  site  16. 

Notes  for  .find: 

1.  All  sites  found  are  stored  on  the  site  list  in  order  of  proximity  to  the  taiga  location  (sorted  by 
distance  from  target). 

2.  The  number  of  sites  found  is  automatically  printed  to  the  active  output  deviceAile. 

3.  If  mask  is  specified,  the  effective  region  is  automatically  set  to  the  current  region  (because  the 
GRASS  mask  is  only  defined  for  the  current  region). 

4.  Region  and  mask  filtering  uses  the  current  resolution  for  the  region  to  test  if  a  point  falls  within  a 
cell  in  the  masking  map. 

5.  In  the  last  two  examples  the  string  "distance  from"  must  be  exactly  matched.  Also,  the  word  "site" 
must  be  exactly  matched. 

6.  If  the  "distance  from"  radius  is  given  as  a  negative  value,  points  outside  the  target  circle  are 
selected;  whereas,  if  a  positive  value  is  given,  points  inside  the  circle  are  selected. 

7.  The  current  region  may  be  changed  with  !g.region  or  Id-zocm  prior  to  doing  a  .find,  and  the  mask 
may  be  set  or  removed  with  a  variety  of  GRASS  commands. 

8.  The  "find>"  prompt  is  given  only  when  input  is  from  a  terminal. 
help  (h) 

Prints  a  help  screen  to  the  output  device  or  file.  Useful  to  have  when  using  s.db.rim  from  a 
terminal,  or  when  writing  a  script  file  erf  commands. 

■input  (.i)  [file ] 

The  lines  in  the  file  given  are  read  and  processed  as  commands  or  data  until  an  end  of  file  is 
reached  or  until  a  .exit  command  is  found.  Input  files  may  call  other  input  files  to  a  nesting 
depth  of  eight.  Without  a  file  name,  stdin  is  used  as  the  input  file. 

list  (.1) 

Lists  the  available  data  bases  in  the  current  mapset  search  path. 

make  Using  the  .make  command  you  create  a  new  data  base  in  the  current  mapset  by  specifying  the 
following  items  which  define  the  screen  (page)  layout  for  displaying  and  printing  the  site 
records,  as  well  as  the  information  fields: 

1)  The  fixed  text  part  of  the  screen  layout. 

2)  The  positions,  types,  and  lengths  of  data  fields. 

Three  fields  must  always  exist  in  a  data  base;  each  of  these  field  types  may  only  occur  once  in  a  data 
base  layout: 

1)  Type ’s’  Site  identification  number  field  (an  integer). 

2)  Type  ’x’  Lasting  coordinate  erf  the  site  (a  double  float). 

3)  Type  ’y’  Northing  coordinate  of  the  site  (a  double  float). 
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Ihe  other  field  types,  which  may  occur  in  any  combination  and  order,  are: 

4)  type  ’i’  An  integer  field. 

5)  type  T  A  double  precision  float  field. 

(always  2  decimal  places  used  for  output) 

6)  type ’t’  A  text  field. 

lach  of  the  fields  can  be  positioned  anywhere  within  the  screen  layout,  which  has  a  limit  of  19  lines  by 
80  columns.  A  maxinnun  of  70  fields  may  be  defined  within  this  space.  A  field  is  specified  in  the 
screen  layout  by  a  tilde  ('),  a  field  type  character,  a  field  name  and  enough  trailing  tildes  to  fill  out  the 
desired  field  length. 

lach  line  following  the  .make  command  is  taken  to  define  a  line  of  the  screen  layout  until  a  .end  is 
reached.  If  a  mistake  is  made  on  any  of  the  input  lines,  the  .make  will  fail.  The  make  information 
may  be  prepared  in  advance  as  a  text  file  (this  facilitates  fixing  mistakes)  and  the  .input  command  can 
be  used  to  read  in  this  file.  An  example  text  file  for  a  data  base  screen  layout  follows,  with  some 
explanatory  notes  and  restrictions. 

.make 

Archaeological  Sites  Database 


Site  #:  'sSite  Entered  By:  “tEnter_by 

Description:  C-14  Ehte:  ‘ iAge"" 

“  tDescript .  V .  . 

*  tDescript .2 . 

*  tDescript .3 . 

Type:  *  tType  .  (Should  be  Arch,  or  Hsl.) 

Ehte:  ' tEnterJChte' . 

North:  'yNorth  East:  ~xEast 

.end 


Notes: 

1)  Any  text  not  preceded  by  a  tilde  (')  character  is  taken  to  be  part  of  fee  constant  or  fixed  text 
portion  of  the  form. 

2)  A  field  definition  begins  with  a  tilde  (~)  character  immediately  followed  by  a  single  character  which 
indicates  the  data  type  of  the  field  (spt,y4/  or  t).  Immediately  following  fee  data  type  character  is  fee 
field  name  of  1  to  16  characters.  Field  names  can  be  composed  of  any  characters  from  the  following 
set:  [AZ^-zv_,0-9j;  the  RIM  program  and  library  do  not  distinguish  upper  and  lower  case  in  field 
names,  so  you  should  avoid  making  names  which  differ  only  in  case,  field  names  may  not  begin  with 
a  numeral  [0-9],  Ihe  rest  of  the  field  length  is  padded  with  tilde  (')  characters  to  the  required 
maximum  length. 

3)  Ihe  ninimum  field  width  is  three  characters;  eg.,  tA”.  Be  sure  field  widths  for  all  fields  are  wide 
cm  nigh  for  the  values  and  strings  you  expect  to  store  there;  e.g.,  UTM  northings  require  at  least  11 

spaces. 

4)  lor  text  fields  it  is  possible  to  continue  a  field  across  more  than  one  line.  This  is  done  by 
appending  a  .1  to  the  field  name  forming  first  portion  of  this  "split  field",  a  .2  for  the  second  portion. 
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etc.  This  text  field  splitting  affects  how  information  is  organized  fen-  input  and  output;  the  composite 
text  string  is  concatenated  (unused  portions  of  fields  axe  retained  as  spaces)  and  treated  as  a  unit  for 
storage  and  queries  to  the  data  base. 

.output  (.o)  [file  or  j  process] 

Causes  all  output  (except  some  error  messages)  from  s.dbjim,  including  that  from  the  .print 
command,  to  go  to  the  named  path/file  (may  be  a  full  or  relative  path  name),  or  to  be  used  as 
standard  input  by  the  process  (a  pipe).  If  no  parameter  is  given,  output  returns  to  stdout, 
usually  the  user’s  terminal.  An  example  of  the  pipe  usage  would  be 

.output  |  grep  "easting"  |  wc  -1  >  Amp/my_count 
A  pipe  is  closed  whenever  the  .output  command  is  given  35am,  or  on  a  .exit  command. 

.pack  (.pa) 

This  should  be  used  when  numerous  data  records  have  been  deleted  to  recover  disk  space  in 
the  RIM  binary'  data  base  files.  It  works  by  doing  a  .backup  to  a  temporary  file;  moving  the 
data  base  files  to  new  names  (*.bakdb*);  running  RIM  to  rebuild  the  data  base;  and,  if  the 
rebuilt  data  base  can  be  opened  and  read,  the  temporary'  files  are  deleted.  The  user  is  informed 
if  this  process  fails.  Packing  can  only  be  done  on  an  open  data  base  located  in  the  user’s 
current  mapset. 

.print  (.p)  [-a  \  -l] 

This  command  outputs  the  full  site  records  for  the  sites  currently  stored  on  the  internal  sites 
list  (result  of  last  .query  or  find).  Without  the  flag,  the  screen  layout  format  is  used.  With  the 
-1  flag,  for  list  format,  the  field  name  followed  by  the  contents  are  output  one  field  per  line. 
The  -a  flag  also  outputs  in  the  list  format  but  with  a  add  line  and  a  .end  line  surrounding  each 
site  record  printed;  data  files  in  this  form  can  be  read  with  input,  thus  they  form  one  kind  of 
backup  mechanism  and  can  be  used  to  transfer  data  (not  the  data  base  layout)  from  one 
GRASS  system  to  another.  The  destination  for  the  output  is  sc*  by  a  previous  .output 
command  (default  is  stdout). 

.query  (.q)  [  -a  \-d  ]  [  -m  ]  [  -w  ] 

The  .query  command  is  used  to  retrieve  sites  via  an  SOI  .-like  request  to  RIM,  including  a  user 
specified  "where  clause."  All  fields  for  each  site  meeting  the  selection  criteria  are  retrieved. 

The  optional  .query  command  line  parameters  cause  points  not  in  the  region  (-w)  and/or  mask  (-m)  to 
be  rejected,  so  these  conditions  need  not  be  tested  in  the  "where  clause."  The  -a  flag  causes  the 
retrieved  sites  to  be  appended  to  those  previously  retrieved  by  .query  or  .find;  duplicate  entries  are 
automatically  discarded.  The  -d  flag  causes  selected  sites  to  be  deleted  from  the  current  list,  if  present. 

After  the  query  command  line,  any  number  of  lines  may  be  entered  to  define  the  SQL  "where"  clause. 
A  .end  line  is  required  to  finish  the  request  and  begin  data  retrieval.  See  examples  below. 

The  "distance  from"  clause  may  also  be  used  as  additional  selection  criteria  exactly  as  described  in  the 
examples  and  notes  for  find.  It  must  be  entered  as  a  separate  line  to  the  query  prompt. 

The  retrieved  records  may  be  printed  at  time  erf  retrieval ,  rather  than  after  the  completion  of  the  query 
command  by  including  a  .print  (.p)  line  with  the  same  options  for  print  format  as  in  the  .print  command 
(see  above);  eg.,  .p  -a  to  output  in  the  "list  add'  format.  The  .print  clause  must  be  entered  as  a 
separate  line  to  the  query  prompt.  This  feature  is  most  useful  when  working  with  very  large  data  bases 
where  retreval  time  is  significant.  See  example  2  below. 


Example  1: 


query > where  density  <20  and  (date  =  "10/14/89” 
query > or  county  eq  "San  Marcos") 
query>  .end 
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Example  2: 

query  > where  east  <600000  and  name  like  "*  Jones*" 
query  >  distance  from  site  12  3000 
query  >  .print  -a 
query  >  .end 

Example  3: 

query  >.end 

The  where  and  distance  from  clauses  are  each  optional.  If  both  are  omitted,  only  the  mask  and  region 
on  the  .query  command  line  restrict  the  search;  if  mask  and  region  are  also  omitted,  all  sites  will  be 
retrieved  (Example  3).  When  querying  few  sites  the  where  clause  is  processed  first,  the  current  region 
and  mask  tested  next  (if  requested),  then  the  distance  from  clause  is  applied;  a  site  must  pass  all  tests  to 
be  put  on  the  internal  site  list  for  output  by  other  commands. 

Notes:  (Also  see  Notes  for  find) 

1.  The  retrieved  sites  are  stored  on  the  internal  site  list  in  the  order  returned  from  the  data  base  by 
RIM,  not  necessarily  in  site  number  order  or  the  order  the  data  was  loaded.  A  "distance  from"  clause 
results  in  a  final  sorting  by  proximity  to  target. 

2.  See  the  RIM  Use^s  Manual  for  additional  information  on  the  "where"  clause  in  the  "select" 
command,  especially  the  quotes  required  for  matching  character  string  fields,  and  tire  allowed 
comparison  operators. 

3.  In  the  where  clauses  of  the  examples,  "density”,  "date",  "county",  east”,  and  "name"  are  field  names 
(column  names  in  RIM)  defined  when  the  user  initially  makes  the  data  base. 

4.  Each  .query  or  .find  resets  the  internal  ate  list  (even  unsuccessful  ones),  unless  the  -a  or  -d  flags  a  e 
used. 

,read_site  (.re)  sitejist  [comment afield ] 

This  command  reads  an  existing  GRASS  site  list  and  creates  a  data  base  record  for  each  site.  If 
the  comment  or  description  field  erf  all  entries  in  the  site  list  begin  with  #  and  a  number,  the 
number  becomes  the  site  number  in  the  data  base.  If  some  erf  the  sites  in  the  GRASS  site  list 
do  not  have  a  #  at  the  beginning  of  the  comment  field,  the  sites  are  numbered  sequentially 
starting  with  1.  (These  options  are  similar  to  the  way  the  GRASS  si tes  to- raster  [in  sjnenu] 
works.) 

If  a  data  base  field  name  "commenGfidd"  is  entered  on  the  command  line,  the  comment  will 
be  stored  in  that  field  for  each  site.  If  an  integer  or  float  field  is  specified,  an  attempt  is  made 
to  interpret  tire  comment  as  that  type  of  number;  if  tins  interpretation  fails,  0  or  0.0  is  stored. 

If  the  site  number  duplicates  one  already  in  the  data  base  or  found  earlier  in  the  site  list,  it  is 
not  added. 

Chce  the  sites  have  been  loaded  by  jeacLsite,  use  change  (or  the  interactive  version)  to  add 
data  to  other  fields  for  those  sites. 

.remove 

This  command,  which  requires  a  "y"  as  confirmation  on  the  next  line,  entirely  removes  the 
three  binary  files  which  constitute  your  RIM  data  base.  Use  with  care.  Backup  files  must  be 
removed  individually  by  the  user,  if  desired,  from  the  SLOCATIONAim/sites  directory. 
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jhow  (jh) 

This  command  is  used  to  output  the  screen  or  page  layout  as  defined  for  the  current  data  base. 
It  serves  as  documentation  of  the  data  base  definition  and  as  a  reminder  for  field  names,  types 
and  lengths.  By  using  an  editor  to  surround  the  output  of  .show  with  make  and  end  lines,  it 
can  be  used  to  reload  the  data  base  definition  with  input. 

jitejist  (.si )  file_name  [field _name] 

This  command  writes  the  site  locations  and  the  site  numbers  to  the  specified  file  in  the  sitejist 
directory  in  the  current  mapset.  If  the  file  exists,  the  sites  are  appended  to  the  current  list, 
otherwise,  a  new  site  list  file  is  created.  A  "field_name"  may  be  optionally  specified;  if  so,  the 
contents  of  that  field  (retrieved  from  the  appropriate  site  record)  are  inserted  as  the  comment 
(following  a  ’#)  in  the  site  list.  The  site  number  is  used  if  no  field  name  is  supplied. 

A  comment  line  is  inserted  in  the  sitejist  file  with  the  current  date  and  time  and  the  name  of 
the  data  base  producing  the  site  locations.  The  fonnat  used  for  each  site  is: 

easting  |  northing  |  Comment 

sables  (s) 

Prints  the  table  structure  of  the  currently  opened  RIM  data  base.  This  is  the  same  output 
generated  by  a  "list  *“  command  when  running  RIM  manually.  The  information  for  the  table 
named  "data"  is  useful  for  review  of  the  user's  field  definitions.  The  information  for  the  two 
other  tables  is  for  internal  use  by  s.dbjim. 
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SECTION  TWO  -  THE  INTERACTIVE  VERSION 
SYNOPSIS 

s.dbj-im 

DESCRIPTION 

'The  interactive  version  of  s.db.rim  allows  you  to  create,  manage  and  query  information  about  site 
locations  (sites)  across  the  landscape.  Operations  are  done  on  a  data  base  through  a  series  of  menus 
explained  below.  Most  of  the  menus  use  VASK  screens;  the  user  should  become  familiar  with  keys 
that  move  the  cursor  among  the  fields  to  be  entered  (RETURN,  ENTER,  CTRL-L,  CTRL-K,  etc.). 

THE  MAIN  MENU 

Relow  is  the  main  menu.  Option  1  is  the  default.  Note  the  status  line  at  the  top  of  the  menu,  and  the 
fact  tliat  8  records  have  been  selected  by  the  latest  find  or  query  operation  (between  items  2  and  3). 
Note,  also,  that  (TRIG  can  be  used  to  exit  from  this  menu  (and  most  other  menus  in  the  program) 
back  to  the  GRASS  prompt.  The  specifics  of  each  menu  choice  are  described  below. 

s.dbrim  MAIN  MENU  Version  1.4 

Data  base  <  water  >in  mapset  <rono  >open.  25  records. 

1  Open  a  data  base 

2  list  available  data  bases 

-  Retrieve/Output  Site  Records  (8  currently)  -- 

3  TTnd  sites  in  proximity  to  a  Target  point 

4  Query  to  select  site  records  (SQL) 

5  Show  selected  site  records  on  Terminal 

6  Display  maps/selected  sites  on  graphics  terminal 

7  Output  selected  site  records  to  Printer  or  File 

8  Create  a  sitejist  from  selected  records 

.  Add/Edit  Site  Records  . 

9  View  a  single  site  record 

10  Add  a  site  record 

1 1  Change  a  site  record 

12  Delete  a  single  record  or  all  selected  records 

. Other  functions  --  Shell  Command  -  Exit . 

13  Make  a  new  data  base  &  Management  functions 

14  Execute  a  shell  command 
0  Done  --  Exit  from  s.dbjim 

AF1ER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>  TO  CONTINUE 
(OR  <Orl  OTO  EXIT  THIS  PROGRAM) 

1.  Open  a  data  base.  If  a  data  base  is  already  open,  it  is  closed  before  the  requested  one  is  opened. 
Only  data  bases  in  the  user’s  current  mapset  may  be  modified;  others  are  opened  in  read-only  mode; 
this  will  be  indicated  on  line  2. 

2.  list  available  data  bases,  l  or  each  mapset  in  the  current  GRASS  mapset  search  path,  the  names  of 
the  existing  data  bases  arc  listed. 

3.  "f  ind"  sites  in  the  data  base  relative  to  a  specified  target  location.  This  is  used  to  select  sites  based 
on  proximity  to  the  target  and.  optioiuilly.  sites  within  the  current  region  and,  optionally,  sites  falling  in 
active  cells  within  the  current  GRASS  mask.  Two  modes  of  targeting  are  provided:  the  N  sites  closest 
to  the  target,  and  all  sites  within  (or  outside")  a  circle  of  specified  radius  from  the  target.  The 
MND/QUERY  TARGET  MENU  discussed  Ixtlow  accepts  rcgion/maskAaiget  specifications  If  m  the 
u-er.  Ihe  selected  sites  ;tre  then  displayed  one  at  a  tinre  until  C1RI.-C  is  entered;  then  i  >*hcr 
ojx  rations,  choices  5-8,  etui  lx-  done  with  these  sites,  llie  line  on  the  menu  between  2  and  3  d*>w  s  the 
numlxT  of  sites  currently  selected  b\  choices  3  or  4. 
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4.  "Query"  sites  in  the  data  base  using  an  SQL-like  "where  clause,"  including  specifications  for 
region/mask/taiget  (circle  only)  as  in  3,  above;  see  FINEVQUERY  TARGET  MENU  section  below. 
The  where  clause  can  test  for  ranges  or  matches  for  numeric  data  base  fields,  or  matches  on  full  strings 
or  substrings  for  text  fields.  The  selected  sites  are  then  displayed  one  at  a  time  until  CTRL-C  is 
entered;  then  other  operations,  choices  5-8,  can  be  done  with  these  sites.  This  clause  is  entered  on  a 
menu  described  below;  see  QUERY  COMMAND  MENU  section,  below. 

The  where  clause  may  use  parentheses  (  )  to  control  the  order  of  comparisons.  Held  names  are  not 
case  sensitive  within  where  clauses.  The  following  comparison  operators  are  valid  for  all  types  of 
fields: 


or 

= 

ne 

or 

o 

or 

>= 

le 

or 

<J= 

or 

> 

It 

or 

< 

String  comparisons  are  case  sensitive  and  are  done  character  by  character.  Substrings  comparisons  may 
be  done  with  the  "like"  operator  as  in: 

where  name  like  "*  Jones*" 

Note  that  file  string  being  tested  against  the  name  field  for  each  record  is  in  quotes  (single  or  double) 
and  that  wild  card  comparisons  can  be  done  in  file  standard  way  with  ’*’  and  ’?  characters. 

Logical  comparisons  may  also  be  combined  with  those  operators  above.  The  permitted  logical 
operators  are: 

and  cr  not 

The  following  complex  example  should  be  examined.  The  line  breaks  can  occur  between  any  tokens 
(words,  values,  operators),  except  within  quoted  strings. 

where  (name  like  "♦Jones*"  or  name  =  "Smith") 
and  (  (  site  <300  and  not  (site  -  251  or  ate  eq  15)  ) 
or  east  <601000  ) 

5.  This  choice  will  display  the  site  records  resulting  from  file  last  find/query  one  at  a  time  on  the 
terminal.  Use  ESC  or  enter  a  number  to  display  another  record  and  CTRL-C  to  end  the  display. 

6.  If  a  graphics  monitor  is  active,  the  locations  of  the  selected  sites  will  be  displayed.  The  user  may 
choose  to  erase  the  screen;  display  raster,  vector,  and/or  site  maps;  or  display  the  selected  sites  from  the 
data  base.  These  maps  are  requested  through  the  following  interactive  screen.  Just  enter  ESC  to  skip 
this  step.  If  no  data  base  sites  are  currently  selected,  that  section  of  the  menu  will  not  appear;  but  the 
menu  can  still  be  used  to  display  the  cither  types  of  maps.  This  display  function  is  a  major  added 
function  of  the  interactive  version  of  the  program;  display  is  not  so  easy  in  the  command  version. 
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SELECTION  MENU  FOR  ITEMS  TO  DISPLAY 

Enter  raster  and/or  vector  map  names,  if  desired 

_  Raster  map  to  display 

_  Vector  map  to  display  in  color _ 

_  Site  list  to  display 

Dpoints  with:  size=3_  tvpe=bax  color=white. 

_  Display  currently  selected  sites  (enter  x) 
d. sites  with:  size=6_  type=x _ coior=red 

_  Erase  graphics  screen  (enter  x) 
derase  Mack _ 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SOTO  CONTINUE 
(OR  <Ctrf-C>TO  CANCEL) 


7.  This  selection  results  in  a  screen  prompting  for  the  name  of  the  file  to  output  the  selected  site 
records  to,  and  for  optional  formatting  selection.  If  the  file  name  is  lp,  the  site  records  are  sent  to  the 
printer.  The  optional  formatting  choices  are  for  export  of  data  in  list  format  (see  .print  in  the  first  part 
of  this  manual  page  for  s.db.rim  for  information  and  examples). 

8.  Using  this  choice  you  can  write  (or  append)  the  currently  selected  sites  to  a  GRASS  sitejist  file  in 
your  current  mapset.  A  short  menu  prompts  for  the  name  of  the  sitejist  file,  and  also  for  the  name  of 
a  field  to  be  used  for  the  "comment"  in  the  sitejist  (the  site  number  is  the  default  field).  The  curre  t 
date  and  time,  and  the  names  of  die  mapset  and  data  base  in  use  are  entered  as  an  information  line  in 
the  sitejist  file.  Note  that  various  kinds  of  raster  map  layers  can  be  produced  from  a  s.db.rim  data 
base  by  writing  sitejists  with  different  fields  as  "comments”  then  converting  the  sitejists  to  raster  files 
with  sjnenu. 

9.  Choices  9  12  operate  on  only  a  single  ate  and  do  not  use  or  modify  the  internal  list  of  sites  selected 
by  find/query  (choices  3  or  4).  Choice  9  is  the  way  to  view  a  single  site  record,  selected  by  site 
number.  After  viewing,  ESC  will  allow  entry  of  another  site  number  and  CTRL-C  will  exit  to  the  main 
menu. 

10.  Use  this  selection  to  add  a  new  site  record  to  the  data  base.  (A  new  site  is  one  whose  site  number 
does  not  currently  exist  in  the  open  data  base.)  After  making  this  selection,  the  data  base  layout  will  be 
displayed  and  you  should  enter  the  available  information  appropriate  to  each  field;  the  only  required 
entry  is  the  site  number  field.  If  values  for  numeric  fields  are  not  entered,  zero  values  will  be  stored. 
Unused  portions  of  text  fields  are  stored  as  strings  of  spaces. 

1 1 .  After  making  this  selection  and  specifying  the  site  number  to  change  field  information  for,  the  data 
is  entered  ;is  for  choice  10,  except  that  the  site  number  cannot  be  changed.  (I he  command  version  of 
the  program  has  provision  for  making  bulk  changes  after  a  find  or  query;  see  .change.) 

12.  To  delete  a  single  record,  enter  its  site  number  when  requested.  All  site  records  ch< 'sen  by  the  last 
find/query  oj>e ration  may  fie  deleted  by  entering  "list"  in  place  of  the  site  number.  BE  CAR1 JT1  with 
this,  deleted  records  are  really  gone. 
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13.  This  choice  starts  a  new  menu  with  less  commonly  used  functions.  See  MANAGEMENT  MENU 
section  below. 

14.  The  program  will  prompt  you  for  one-line  Shell  Commands  until  you  enter  just  a  <RETURN>  to 
return  to  the  main  menu.  Often  useful  for  changing  the  GRASS  region,  setting  a  MASK,  etc. 

FINDAJUERY  TARGET  MENU 

This  is  the  screen  to  set  up  the  region^naskAarget  information  for  the  find  choice  (3)  and  the  query 
choice  (4),  except  that  item  B  is  omitted  for  choice  (4).  The  choice  to  append  or  delete  selected 
records  will  only  be  given  after  a  successful  find  or  query  has  stored  some  records  on  the  internal 
record  list.  See  .find  ;uul  .query'  for  more  information. 

If  a  graphics  nxrnitor  is  not  active,  the  "mouse"  item  is  omitted  from  the  screen;  and,  if  a  mask  is  not 
set,  that  choice  is  omitted.  The  choices  entered  on  this  example  screen  will  result  in  all  the  sites  within 
a  1500  (meters)  radius  of  the  target  point  (to  be  chosen  with  the  mouse)  being  selected  ;md  stored  on 
the  internal  site  list  by  find  or  query.  They  are  stored  in  order  of  proximity  to  the  target.  If  a  site  is 
used  as  the  target,  it  is  always  the  first  in  the  retrieved  list  (useful  for  just  selecting  are  site  by 
number).  If  a  mouse  is  chosen  to  select  the  target  point,  a  menu  to  display  reference  maps  is  presented, 
exactly  as  in  choice  (6),  prior  to  actually  activating  the  mouse. 

QUERY/FIND:  REGION/MASK/TARGEr  SELECTION  MENU 
Data  base  <arch>  (READONI  ,Y)  in  mapset  <PI RMANI  -NI  >  open .  113  records. 

Mark  requests  with  V  and  enter  required  values. 

Respect  current  region  _ 

Respect  current  MASK  x 
(forces  current  region) 

A  find  all  sites  within  (or  outside)  a  circular  target  x 

and  give  the  radius  (negative  for  outside)  1500.00 _ 

OR 

B.  find  a  number  of  sites  nearest  a  point 

and  the  number  of  sites  requested  _ 

After  selecting  A  or  B,  complete  one(!)  of  these: 

1.  x  to  select  target  point  with  mouse  x 

2.  Enter  site  number  for  target  point  _ 

3.  Target  coordinates  east  0.00 _ 

north  0.00 _ 

Append/Delete  to  current  FINEVQUERY  site  list  (a  |  d)  _ 

Reset  to  default  choices  for  this  menu  _ 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 

QUERY  COMMAND  MENU 

The  following  screen  completes  the  information  for  a  query  (choice  4).  It  may  be  left  blank  if  no 
"where  clause"  is  required.  After  a  successful  query,  the  selected  records  are  displayed  one  at  a  time 
by  hiring  escape;  CTRL-C  will  quit  the  display  and  return  to  the  main  menu  where  several  choices  of 
operation  on  the  retrieved  sites  are  offered. 
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QUERY  CXJMMAN1)  (  ONST  RUCTION  SCREEN 
Data  base  <  A  >in  mapset  crine  test  >open.  25  records. 
The  SQI .  select  query  will  use  the  current  region 
and  a  target  clause  of  ’distance  from  596463.15  4919041.88’ 

where  date  =  10/16/89 _ 


(Enter  .show  on  a  line  to  review  screen  layout  and  field  names.) 

ALTER  COMPLETING  Al  l.  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 


MANAGEMENT  MENU 

Choice  13  from  the  main  menu  presents  this  menu.  Each  item  is  discussed  below. 

s.db.rim  DATA  RASE  MANAGEMENT  MENU 
Data  base  <A>in  mapset  <rim_test>open.  15025  records. 

1  Make  a  New  Data  Base  in  Current  Mapset 

2  List  Available  Data  Bases 

3  Remove  (1TRMANENTI  ,Y)  Data  Base  from  Current  Mapset 

4  Recover  a  Data  Base  from  a  RIM  ASCII  Hie 

5  Show  Screen  layout  of  Current  Ebta  Base 

6  Backup  (UNLOAD)  Data  Base  to  RIM  ASCII  Format  Hie 

7  Pack  the  Gurcnt  Data  Base 

8  Read  a  Site  list  into  the  Current  Data  Base 

0  Return  to  Main  Menu 
()_  Your  selection 

ALTER  G  MPLETING  ALL  ANSWERS,  HIT  <ESC>TO  aWITNUE 
(OR  Tfrl-OTO  CANCEL) 

1.  Use  this  choice  to  create  a  new  s.db.rim  data  base  in  the  current  GRASS  mapset.  See  section 
below  on  MAKE.  A  NEW  DATA  BASI-l 

2.  list  available  data  bases.  like  2  on  MAIN  MENU. 

3.  Delete  an  entire  data  Ixise  from  the  current  mapset.  The  name  of  the  data  base  and  additional 
confirmation  of  the  action  are  prompted  for. 
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4.  Choice  6  allows  backup  of  the  definition  and  data  parts  of  a  data  base  to  a  transportable  text  file. 
To  rebuild  (or  build  for  the  first  time)  a  s.db.rim  data  base  from  one  of  'bese  text  files  do  the  following 
steps: 

#  see  if  the  rim  directory  exists. 

Is  $ LOCATI ONAi  m/si t es 
# if  the  directory  was  not  found,  make  it. 
nikdir  SLOCATIONAi m/sites 
#change  directory  to  it. 
cd  SLOCATION/ri m/sites 

#have  rim  build  the  binary  data  base  files, 
rim 

RIM>  input  Vpath/to/ycxir/textfile’ 

RIM>exit 

Ihe  data  base  is  thus  created  in  the  current  niapset.  Several  s.db.rim  comnumds  should  be  run  to 
verify  the  integrity'  of  the  newly  created  data  base. 

5.  Ihis  merely  shows  the  screen  layout  of  the  currently  open  data  base.  It  is  a  useful  way  to  quickly 
see  the  layout  and  review  the  field  names  and  types. 

6.  When  backing  up  to  a  text  file,  the  RlM  UNLOAD  command  is  run  with  the  output  directed  to  a 
file  of  the  user’s  choice.  See  4  above.  It  is  wise  to  do  this  operation  after  extensive  charges  or 
additions  of  data  records.  The  resulting  text  file  can  be  written  to  tape  for  preservation,  or  shared  with 
other  GRASS  systems,  i?  desired. 

7.  After  deleting  a  large  number  of  site  records,  some  "wasted"  disk  space  will  l*  present  in  the  binary 
data  base  files.  This  procedure  will  perform  an  unload  ;tnd  a  reload  automatically  to  recover  this 
unusable  disk  space.  If  there  is  any  problem  reopening  the  data  base  after  packing,  the  user  is  notified 
and  can  recover  in  various  ways  depending  on  the  backups  which  have  been  done. 

8.  Data  may  be  loaded  into  a  data  base  from  an  existing  GRASS  sitejist.  This  procedure  will  prompt 
for  the  sitejist  name  and  then  add  the  sites  to  the  currently  open  data  base.  If  all  sites  in  the  list  have 
a  comment  field  of  the  form  "#*alue  ....",  the  value  is  used  as  the  data  base  site  number,  otherwise  the 
sites  are  numbered  sequentially  beginning  with  1 .  Only  the  site  number  and  location  coordinates  are 
loaded  for  each  site  record  by  this  procedure;  other  fields  may  be  later  added  with  the  "charge" 
function.  See  xead_sites. 

MAKE  A  NEW  DATA  BASE 

After  entering  the  name  of  the  new  data  base  you  wish  to  create  (7  characters  maximum),  you  then 
decide  how  to  input  the  information  required.  This  input  may  be  from  a  text  file,  or  may  be  entered 
directly  using  the  editor  of  your  choice;  the  former  is  recommended. 

See  .make  for  the  way  to  define  a  data  base  and  record  (form)  layout. 
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NOTES 

Ibis  program  is  included  in  the  GRASS  4.0  release,  but  is  not  automatically  compiled  witli  other 
(iRASS  commands.  Ihe  user  mast  compile  this  program  separately. 

s.ilb.rim  interfaces  to  tlie  RIM  program.  Roth  rim  and  s.db.rim  contain  FORTRAN  code.  The  aser 
must  have  access  to  a  FORTRAN  compiler  in  order  to  compile  and  use  s.db.rim.  See  the  FILES 
section,  below,  for  the  h cation  of  source  aide. 

A  "date"  type  field  should  be  added  to  future  versions.  This  version  only  allows  storing  of  dates  as 
strings  (unless  the  user  axles  them  to  integers),  and  thus  only  string  type  searches  can  be  made  for 
dates. 

FILES 

Ihe  source  axle  for  RIM  is  located  under  $GISBASE/../src.related/rim 

llie  sextree  axle  for  s.db.rim  is  located  under  SGLSBASF/ _/src garden/grass.rim/s.dbjim 


SEE  ALSO 

RIM  User’s  Manual,  by  James  Fcoc,  Academic  Computing  Services,  Univ.  of  Washington.  See 
especially  Appendix  B  on  redistribution  of  RIM. 

GRASS  4.0  Installation  Guide,  by  James  Westervelt  and  Michael  Shapiro,  U.S.  Army  Construction 
lingineering  Research  Laboratory 

d.icons,  d.points,  gjnapsets,  g.region,  r.mask,  sjn. ascii,  s.menu,  s.outxtscii,  v.db.rim 
AUTHORS 

James  Hinthome  and  David  Satnik,  GIS  Laboratory,  Central  Washington  University,  Hlensburg,  WA 
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NAME 

s.in.ascii  -  C  onverts  an  ASCII  listing  of  site  locations  and  their  descriptions  into  a  GRASS  site  list  file. 
(GRASS  Sites  Program) 

SYNOPSIS 

sdn.ascii 
s-in-ascii  help 

s-in-ascii  sites— name  [input  =name]  [fs=character^pace|tah) 

DESCRIPTION 

s.in.ascii  converts  ail  ASCII  listing  of  site  locations  and  category  la! vis  inti'  a  tile  in  GRASS  site  list 
file  format. 

Input  can  lv  entered  via  standard  input  or  from  the  file  input  name.  Inch  line  ot  in|xit  should  contain 
the  easting,  northing,  and  (optionally)  the  category  label  associated  with  a  site,  llie  fs  name  option 
(where  nanu •  is  either  a  character,  a  space,  or  a  tab)  can  lv  used  to  specify  tlie  use  of  a  jxirticular  field 
separator  between  these  three  input  fields,  iliis  is  useful  when  input  is  obtained  from  other  programs 
(see  NOlliS.  below).  ( Xitput  is  stored  in  the  file  sites  name  and  placed  in  the  sitejists  director, 
tutder  the  user’s  current  mapset. 

Ihe  GRASS  program  s. out. ascii  can  be  used  to  perform  the  reverse  function,  converting  a  file  in 
GRASS  site  list  format  into  an  ASCII  listing  of  eastings,  northings,  and  category  labels  associated  with 
site  locations. 

Parameters: 

sitesrtame  Name  of  the  new  GRASS  site  list  file  to  lv  output. 

input  name  Name  of  an  existing  ASCII  file  containing  site  locations  and  labels. 

fs=characterfspace|tab  The  field  separator  separating  the  easting,  northing,  and  category  label  in 

each  line  of  the  input  file.  Ihe  field  separator  c;ui  lv  a  character,  a  spice, 
or  a  tali. 

Default:  space 

s.in.ascii  can  lv  run  either  non- interactively  or  interactively.  The  program  will  lv  nut  non 
interactively  if  the  user  specifies  a  name  to  be  assigned  to  the  sites  file  output,  the  name  of  an  existing 
ASCII  file  containing  input,  and  (optionally)  a  field  separator  fs  appearing  in  the  input  file,  using: 

s-in-ascii  sites  mame  [input  =/ta/ne|  [fs=characfer^pace|tab] 

Alternately,  the  user  can  simply  type  sdn-ascii  on  the  command  line,  without  program  arguments,  hi 
this  case,  the  user  will  lv  prompted  for  paranvter  v;ducs  using  the  standard  GRASS  parser  interlace 
described  in  the  manual  entry  for  parser.  If  the  user  does  not  specify  the  name  of  an  input  file 
containing  site  locations  and  (optionally)  category  labels,  these  should  be  entered  to  the  program  v  ia 
standard  input. 

NOTES 

Other  GRASS  programs  can  be  used  to  produce  output  in  a  format  suitable  for  input  to  s.in.ascii.  l  or 
example,  the  user  might  pipe  output  produced  by  d.where  into  s.in.ascii  to  create  a  site  list  file  called 
my.sites  containing  site  locations  pointed  to  with  the  mouse,  as  illustrated  below.  In  this  example  it 
was  unnecessary  to  specify  the  field  separator  used  in  the  input,  since  d.where  output  separates  the 
easting  anil  northing  v;dues  with  spaces,  and  spaces  are  the  defaidt  field  separator  assumed  by 
s.in.ascii. 

d.where  |  s.  in -ascii  sites -my  .sites 
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SEE  ALSO 

d.points,  duties,  d.what.rast,  d.where,  s.out Mscii,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  C>nstniction  Engineering  Research  Laboratory 
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NAME 

s.menu  -  Accesses  and  manipulates  GRASS  site  location  data. 

(GRASS  Sites  Program) 

SYNOPSIS 

soneno 

OVERVIEW 

The  sjnenu  program  provides  the  user  with  the  capability  of  interfacing  site  location  data  with  the 
geographic  data  in  raster  map  layers.  Two  types  of  spatial  analysis  reports  on  sites  can  lie  generated, 
and  an  interface  to  the  "S’  statistical  package  is  provided. 

DESCRIPTION 

The  sjnenu  program  is  an  interface  to  functions  that  allow  the  user  to  manipulate  GRASS  site  "lists." 
A  site  list  is  a  list  of  eastings  and  northings  describing  the  location  of  some  point  feature.  It  can  also 
contain  a  category  value  and  category  label  for  each  site  location.  The  program  is  interactive.  After 
typing  s.meno  on  the  command  line,  the  user  selects  site  functions  from  a  menu. 

The  main  menu  is  shown  below : 

SITES  MAIN  MENU  (current  list:  no  sites) 

LOCATION:  spearfish  REGION  4928000.00(N)  4914000.00(S)  100.00  (RES) 

MAPSET:  PERMANENT  609000.00(E)  590000 .00(W)  100.00  (RES) 

MASK:  none 

Please  select  one  of  the  following 

1  Read  an  existing  site  list 

2  Mask  current  site  list 

3  Save  the  current  site  list  in  your  mapset 

4  Check  site  list  for  duplicate  sites 

5  Edit  site  list  using  a  UNIX  editor 

6  Convert  site  list  to  raster  file  (0/1) 

7  Convert  site  list  to  raster  file  (frequency  of  occurrence) 

8  Run  reports  on  the  current  site  list 


stop  Leave  the  s.menu  program 

At  the  top  of  the  menu  is  general  information  about  the  user’s  current  MAPSET,  LOCATION,  etc.  Note  the 
above  message  in  parentheses  "current  list:  no  sites."  This  message  will  vary  depending  on  the  status  of  the 
list.  For  example,  after  the  user  reads  the  existing  site  list  file  arch_sites,  the  message  would  read  (given 
the  geographic  region  indicated):  "current  list:  25  sites,  24  in  current  region." 
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1  Read  an  existing  site  list 

'ihis  option  will  copy  ;ut  existing  site  list  file  into  the  current  site  list  within  the  sites  server.  1  listing 
site  lists  are  stored  under  a  GRASS  data  base  and  are  pulled  into  the  s. me  rut  server  via  this  option. 
(Xlier  sites  menu  functions  operate  only  on  the  current  site  list  file  in  the  server  -  you  must  therefore 
"read  an  existing  site  list"  file  BITORU  performing  any  of  the  other  sites  menu  functions. 

Note:  Site  lists  can  tie  created  and  placed  into  a  GRASS  data  base  using  s.menu  option  5  (edit) 
followed  Its  option  3  (save).  However,  the  user  can  also  create  site  lists  using  other  methods  or 
programs.  One  simple  way  to  do  this  is  to  create  a  site  list  file  in  the  appropriate  format  using  any 
text  editor  (eg.,  "vi"),  and  to  put  this  site  list  file  under  the  sitejists  directory  under  the  user’s 
current  GRASS  mapset  (i.e.,  under  SlGCATION/siteJists).  The  user  can  do  this  either  inside  of 
GRASS  or  outside  of  GRASS.  Alternately,  the  user  can  nm  other  GRASS  programs  that  format  their 
output  us  a  (iRASS  site  list  file  (r. random,  s.db.rim,  v.mkquads,  v. to. sites),  or  the  user  can  use 
UNIX  programs  like  awk  and  sed  to  format  other  GRASS  programs’  output  in  the  form  erf  a  site  list 
file  (d.what  rast ,  d.what.vect). 

2  Mask  current  site  list 

The  site  list  can  be  reduced  to  a  subset  that  includes  only  sites  that  fall  in  specific  categories  within  a 
specified  ruster  map  layer.  The  user  will  be  asked  to  specify  the  name  of  a  raster  map  layer  to  form 
the  basis  for  the  mask,  and  will  then  be  allowed  to  specify  categories  from  this  raster  map  that  will 
limit  the  site  list.  As  with  r.mask,  the  category  values  selected  designate  the  areas  of  the  map  in 
which  information  will  remain.  Aeas  assigned  category  values  not  selected  will  be  re  assigned  to 
category  value  "0"  ("no  data"). 

Note:  This  masking  operation  is  performed  only  against  the  site  list  itself  and  not  against  other  raster 
map  layers.  If  the  user  wishes  to  analyze  masked  raster  map  layers,  a  mask  should  be  created  using 
the  r.mask  program. 

3  Save  the  current  site  list  in  your  mapset 

Ihe  current  site  list  can  be  stored  permanently  in  your  current  mapset  with  this  option.  You  will  be 
asked  to  name  the  saved  site  list  and  to  provide  a  short  description  of  it.  Saved  site  lists  can  be 
retrieved  (option  1)  during  later  runs  of  sjnenu.  Once  saved,  these  site  list  files  can  be  used  with 
other  (iRASS  programs,  like  d.sites,  d.points,  d. icons,  p.icons,  ssurfjdw,  and  s.db.rim. 

Note:  Saved  lists  w  ill  lie  removed  if  the  GRASS  mapset  tuider  which  they  are  stored  is  removed. 

4  (  heck  site  list  for  duplicate  sites 

It  is  not  desirable  that  a  site  list  contain  multiple  references  to  the  same  site.  Ihis  option  attempts  to 
recognize  duplicate  sites.  Duplicates  are  displayed  to  the  user  and  can  1*  removed  automatically  if 
the  user  desires.  IXiplicates  can  also  be  removed  by  hand  using  option  5  (edit). 

5  T  Jit  site  list  using  a  UNIX  editor 

Ihe  user  can  modify  the  current  site  list  or  create  a  new  site  list  by  hand  using  a  UNIX  edjtor.  You 
will  lx-  asked  to  specify  the  text  editor  you  prefer  to  use.  You  sh<xild  exercise  some  care  if  you 
select  this  option.  lines  in  the  site  list  which  have  invalid  formats  will  be  (silently)  ignored  by 
s.menu.  See  the  (iRASS  manual  entry  sites. for  mat  for  a  description  of  the  site  list  format 

Note:  Ihis  option  will  only  nxxlify  the  site  list  copied  into  the  server.  It  doc.  «v4  modify  the 
original  site  list  stored  unuer  a  (iRASS  mapset.  If  vou  wish  to  mtxlify  a  stored  site  ’ist  Ge,  you  will 
hav  e  to  combine  options  1  tread),  5  (edit),  and  3  (save). 

(t  (  omert  site  list  file  to  raster  tile  (0/1) 

't  oo  can  create  a  raster  tlala  representation  of  the  site  list  in  y<”ir  (iRASS  mapset. 

<  Hu  e  created,  this  raster  map  layer  c;ut  lx:  used  with  other  raster  map  layers  in  further  analyses. 
Allowing  tlx-  user  to  create  a  raster  map  layer  of  sites  <>]x-iis  up  the  full  analysis  capabilities  for  site 
data  that  are  av  ailable  for  ruster  map  lavers  within  (iRXSS. 
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You  have  the  option  of  specifying  the  number  of  cells  to  represent  a  site.  The  minimum  is  one  cell 
per  site.  The  alternatives  are  squares  around  the  site:  3x3,  5x5,  7x7,  etc. 

The  number  of  categories  present  in  the  new  raster  map  layers  will  depend  on  die  format  of  your  site 
list  file  (see  sites. format).  You  can  create  a  non-binary  raster  map  layer  representation  of  your  site 
list  by  creating  the  site  list  in  the  format: 

E|N|  tin  label 

where  E  is  the  Easting,  N  is  the  Northing,  and  tin  label  is  the  description  field.  The  description 
field  consists  of  a  pound  sign  #  followed  by  the  category  value  n  to  be  associated  with  the  site’s  cell 
location,  and  the  category  label  label  for  n. 

If  the  user  does  not  include  a  description  field  starting  with 

tin 

beside  the  Easting  and  Northing  on  every  line  in  the  sites  list  file,  a  binary  raster  map  layer  will  be 
created  instead.  In  the  binary  raster  file,  each  site  w ill  be  represented  as  the  category  value  1 .  Non- 
site  cells  will  be  coded  as  category'  value  0. 

Note  that  only  sites  within  the  current  geographic  region  will  be  considered.  However,  if  the  size  of 
the  sites  is  more  than  one  cell  (  3x3,  5x5,  etc.)  and  a  site  lies  near  an  edge  of  the  geographic  region, 
some  of  the  cells  for  the  site  may  fall  outside  the  geographic  region.  These  cells  will  not  appear  in 
the  raster  map  layer,  and  the  site  will  no  longer  be  3x3  or  5x5  but  will  be  clipped  to  fit  the 
geographic  region. 

7  Convert  site  list  file  to  raster  file  (frequency  of  occurrence) 

You  can  also  create  a  frequency  of  occurrence  raster  map  layer  representation  of  the  site  list  file. 

The  raster  category  values  will  be  coded  as  the  number  of  sites  that  fall  within  the  cell. 

In  this  function,  you  do  NOT  have  the  option  of  specifying  the  number  of  cells  to  represent  a  site. 

8  Run  reports  on  the  current  site  list 

The  current  list  of  sites  is  passed  to  the  report  server  after  removing  sites  that  do  not  fall  within  the 
geographic  region  of  the  user’s  current  GRASS  mapset  (see  g. region).  The  user  then  selects  the 
names  of  one  or  more  raster  map  layers  for  analysis.  Data  at  (or  near)  the  sites  extracted  from  these 
raster  map  layers  form  the  basis  for  all  reports. 

The  user  specifies  the  ’size’  of  a  site  in  cells.  The  ’size’  may  be  specified  as  a  single  cell,  or  as  a 
3x3  square  around  the  site,  or  5x5,  or  7x7,  etc  (where  the  size  is  an  odd  integer). 


The  following  menu  of  reports  is  then  presented: 
SITES  REPORT  MENU 


Please  select  one  of  the  following 

1  Site  characteristics  report 

2  Site  occurrence  report 

3  Convert  data  to  S  input  format 

4  Produce  machine-readable  data  file 

stop  return  to  SITES  MAIN  MENU 
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1  Site  characteristics  report 

this  report  provides  geographic  information  about  each  site. 

Each  site  is  identified  by  description  and  locational  information.  The  ’description’  is  an  identification 
of  the  site.  The  site  location  is  an  easting  and  a  northing.  (Ihe  location  does  not  denote  the  extent 
of  the  site,  since,  for  example,  an  archeologic  site  which  takes  up  two  hectares  would  be  represented 
as  a  single  point). 

The  information  reported  for  each  site  is  displayed  by  raster  map  layer,  and,  within  each  map  layer, 
gives  the  categories  (i.e.,  characteristics)  that  occurred  at  the  site  (as  well  as  a  count  erf  the  number  of 
cells  in  each  category). 

Ibis  can  easily  generate  a  massive  amount  of  information,  which  is  difficult  to  handle  or  tfigest 
quickly.  Iherefore,  option  2  produces  a  synopsis  of  the  information. 

2  Site  occurrence  report 

Ihis  report  provides  aggregate  site  characteristic  information  organized  by  raster  map  layer.  The 
report  produces  chi  square  statistics  for  each  raster  map  layer,  measuring  number  of  expected  sites 
(assuming  a  random  distribution  of  sites)  against  actual  site  occurrence.  The  site  characteristic  is  the 
most  frequently  occurring  cell  category  in  the  site  (i.e.,  the  statistical  mode).  See  the  GRASS  manual 
entry  for  sites. occur  for  details  on  this  report. 

3  Convert  data  to  S  input  format 

This  function  converts  the  GRASS  data  extracted  for  the  sites  into  a  form  usable  by  the  S  statistical 
package.  Ihe  user  provides  a  file  to  con'nin  the  information.  Once  the  file  is  written,  the  user  must 
exit  s.menu,  run  S  on  an  S  data  base,  and  issue  the  S  command 

source  file 

to  bring  the  data  into  the  S  data  base.  (Of  course,  file  would  be  the  name  of  the  actual  file  supplied 
by  the  user.)  Sec  nuinual  entry  sites.S  for  an  explanation  of  the  S  data  structures  created  by  this 
interface. 

4  Produce  machine- readable  data  file 

'Ihis  option  provides  a  mechanism  for  the  user  to  write  his/her  own  reports.  The  data  is  written  into 
a  user-specified  file  as  a  text  file,  which  has  a  format  readable  by  UNIX  utilities  (e.g.,  awk)  or  user- 
written  programs.  See  GRASS  manual  entry  sites.report  for  details  on  this  format. 

FILES 

$1  /X;ATION/site JistMile  > 

SEE  ALSO 

d.icons,  d.graph,  tLpoints,  d.sites,  p.icons,  r .random,  d.what.rast,  d.what.vect,  r.whal,  s.db.rim, 

s.surfidw,  v.db.rim,  vjnkquads,  vjojiles, 

and 

sites.format,  sites.report,  sites.occur,  sites.S 

AUTHORS 

Michael  Shapiro,  U.S.  Army  O instruction  Engineering  Research  Laboratory 
James  Earley,  Arkansas  Archeological  Survey,  University  of  Arkansas 
contributed  the  frequency  of  occurrence  sites  to  cell  function 
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NAME 

s.outxiscii  -  Converts  a  GRASS  site  list  file  into  an  ASCII  listing  of  site  locations  and  their 
descriptions. 

(GRASS  Sites  Program) 

SYNOPSIS 

s.outjiscii 
8.outjiscii  help 

s.out  .ascii  [-ad]  sites  =name  [  fs  =charac  ter  (space  |tab] 

DESCRIPTION 

s. out. ascii  converts  an  existing  site  list  file  (sites  =name)  into  an  ASCII  listing  of  site  locations  and 
(optionally)  their  category  labels,  in  a  format  suitable  for  input  to  other  programs  (e.g.,  d.points, 
m.u2ll,  etc.). 

Each  line  of  output  consists  of  the  easting,  northing,  and  category  label  for  a  site  listed  in  the  named 
sites  file.  The  fs=name  option  (where  name  is  either  a  character,  a  space,  or  a  tab)  can  be  used  to 
place  a  particular  field  separator  between  these  three  output  fields.  This  is  useful  when  output  is  to  be 
manipulated  by  other  programs,  like  awk  or  sed. 

The  GRASS  program  s.in.ascii  can  be  used  to  perform  the  reverse  function,  converting  a  UNIX  file 
containing  eastings,  northings,  and  category  labels  associated  with  site  locations  into  GRASS  site  list 
file  fonnat. 

Flags: 

-a  Output  all  sites  found  in  the  named  sites  file,  rather  than  limiting  output  to  sites 

falling  within  the  current  geographic  region. 

-d  Include  site  descriptions  (category  labels)  in  the  output. 

Parameters: 

sites  =nome  Name  of  an  existing  ate  list  file. 

fs=character|space|tab 

The  field  separator  to  be  placed  between  the  easting,  northing,  and  (optionally) 
category  label  on  each  line  erf  output.  The  field  separator  can  be  a  character,  a 
space,  or  a  tab. 

Default:  space 

s.out.ascii  can  be  tun  either  non-interactively  or  interactively.  The  program  will  be  run  non- 
interactively  if  the  user  specifies  the  name  of  an  existing  ate  list  file  and  (optionally)  a  value  for  fs, 
using  the  form 

s.out.asdi  [-ad]  sites  name  [fs=charac  ter  (space  |tab] 

where  name  is  the  name  of  an  existing  site  list  file  to  be  converted  to  a  brief  ASCII  listing,  and  fs  is 
the  field  separator  to  be  placed  between  output  fields.  Ihe  user  can  also  specify  the  -a  and  -d  options 
to  use  all  sites  in  the  named  sites  file  and  to  include  site  descriptions  in  the  output. 

Alternately,  the  user  can  simply  type  umtjucii  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  parameter  values  using  the  standard  GRASS  parser  interface 
described  in  the  manual  entry  for  parser. 
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NOTES 

The  output  from  s.out. ascii  may  be  placed  into  a  file  by  using  the  UNIX  redirection  mechanism;  eg.: 

s.outaiscii  sites  arcbstes  >  outiile 

s.out. ascii  output  may  also  be  redirected  into  other  programs;  eg.: 

s.out.ascii  sites  =archsites  |  d. points  color  =red  size  =10  type  =diamond 

SEE  ALSO 

d.points,  d.sites,  m.ll2u,  m.u2ll,  s.in.ascii,  and  parser 
AUTHOR 

Michael  Shapiro,  U.S.  Constmction  Lngineerirg  Research  Laboratory 
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NAME 

sjurf.idw  -  Surface  generation  from  sites  data  program. 

( GRASS  Raster  Program) 

SYNOPSIS 

&surfJdw  input  -name  output  =name  [npoints=coun/] 

DESCRIPTION 

s.surf.idw  fills  a  raster  matrix  with  interpolated  values  generated  from  a  set  of  irregularly  spaced  data 
points  using  numerical  approximation  (weighted  averaging)  techniques.  The  interpolated  value  of  a  cell 
is  determined  by  values  of  nearby  data  points  and  the  distance  of  the  cell  from  those  input  points.  In 
comparison  with  other  methods,  numerical  approximation  allows  representation  of  more  complex 
surfaces  (particularly  those  with  anomalous  features),  restricts  the  spatial  influence  of  any  errors,  and 
generates  the  interpolated  surface  from  the  data  points.  It  is  the  most  appropriate  method  to  apply  to 
most  spatial  data. 

This  program  allows  the  user  to  use  a  GRASS  site  list  file,  rather  than  a  raster  map  layer,  as  input. 

The  program  will  be  run  non-interactively  if  the  user  specifies  the  values  of  needed  program  parameters 
and  any  desired  optional  parameter  values  on  the  command  line,  using  the  form: 

s.surfJdw  input  name  output  —name  [npoints  counl\ 

Alternately,  the  user  can  simply  type  susurf-idw  on  the  command  line,  without  program  arguments.  In 
this  case,  the  user  will  be  prompted  for  needed  inputs  and  option  choices  using  the  standard  GRASS 
parser  interface  described  in  the  manual  entry  for  parser. 

Parameters: 

input  =name  Name  of  an  input  site  list  file  that  contains  a  set  of  irregularly  spaced  data  values; 

i.e.,  some  cells  contain  known  data  values  while  the  rest  contain  zero  (0). 

output  name  Name  to  be  assigned  to  the  new  output  raster  map  layer  containing  a  smooth 
surface  generated  from  the  known  data  values  in  the  input  site  list  file. 

npoints  count  The  number  of  points  to  use  for  interpolation.  By  default,  the  12  nearest  points 
are  used  for  interpolation. 

Default:  12 

NOTES 

The  amount  erf  memory  used  by  this  program  is  related  to  the  number  of  non-zero  data  values  in  the 
input  sites  list  file.  If  the  input  site  list  is  very  dense  (i.e.,  contains  many  non-zero  data  points),  the 
program  may  not  be  able  to  get  all  the  memory  it  needs  from  the  system.  The  time  required  to  execute 
increases  with  the  number  of  input  data  points. 

If  the  user  has  a  mask  set,  then  interpolation  is  ally  daie  for  those  cells  that  fall  within  tlie  mask. 
However,  all  non-zero  data  points  in  the  input  map  are  used  even  if  they  fall  outside  the  mask. 

SEE  ALSO 

d.sites,  g.region,  r.mask,  r. surf. contour,  r.surf.idw,  rsurf.idw2,  s.db.rim,  s.menu,  and  parser 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  engineering  Research  laboratory 
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NAME 

v.area  -  Display  GRASS  area  and  [perimeter  information  for  GRASS  vector  map. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.area 
v.area  help 

v.area  [-f]  map  name  j color  =name] 

DESCRIPTION 

'Hie  GRASS  program  v.area  first  displays  the  selected  vector  file.  The  user  then  can  select  an  area  on  a 
map  by  clicking  with  the  mouse  within  the  desired  area.  The  selected  area  will  be  highlighted  in  the 
selected  color  on  the  graphics  display.  On  a  regular  screen,  area  information  will  be  displayed,  in 
square  meters,  hectares,  acres,  and  square  miles.  Perimeter  measurements  also  will  be  displayed,  in 
meters,  feet,  and  miles. 

Ihe  user  can  repeatedly  select  areas  for  analysis,  one  at  a  time. 

Flag: 

-f  fill  selected  area  with  selected  color  on  graphics  display,  rather  than  simply 

outlining  it  in  the  highlight  color. 

Parameters: 

map  -name  Name  of  the  vector  map  layer  to  be  displayed. 

color  =name  Color  in  which  perimeter  will  be  highlighted. 

IX' fault:  red 

If  the  user  simply  types  v.area  without  specifying  program  arguments  on  the  command  line,  the 
program  will  prompt  the  user  for  the  name  of  a  map.  Then  the  user  is  given  the  option  of  specifying  a 
highlight  color,  and  then,  whether  or  not  the  display  of  selected  area(s)  is  to  be  filled,  rather  than 
merely  outlined,  with  the  highlight  color. 

SEE  ALSO 

d.vecl 

AUTHOR 

Unite  Powell,  National  Park  Service,  Denver,  CO. 
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NAME 

v.cadlabel  -  Attaches  labels  to  (binary)  vector  contour  lines  that  have  been  imported  to  GRASS  from 
DXF  format. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.cadlabel 
v.cadlabel  help 

v.cadlabel  li nes=name  lab*is=name 
DESCRIPTION 

v.cadlabel  attaches  labels  to  index  contour  lines  by  using  the  index  contour  lines  and  labels  files  that 
have  been  converted  from  DXF  format  to  GRASS  vector  format  by  the  v.in.dxf  program.  Users  hav  e 
the  option  of  creating  either  binary'  or  ASCII  output  with  v.in.dxf.  Since  v.cadlabel  works  only  on 
binary  vector  files,  the  ASCII  GRASS  vector  ( dig_ascii )  files  that  are  generated  by  v.in.dxf  must  be 
converted  to  binary  GRASS  vector  (dig)  files  using  the  v.in.ascii  program  before  v.cadlabel  can  be 
executed. 

v.cadlabel  searches  a  binary  GRASS  vector  file  of  contour  lines  to  find  the  contour  lines  that  are 
closest  to  each  box  (contour  label)  in  the  binary  GRASS  vector  file  containing  contour  labels.  The  two 
contour  lines  that  are  closest  to  a  box  are  tagged  with  the  same  label  (an  elevation  value)  as  that  of  the 
box. 


OPTIONS 

Program  parameters  are  described  below. 

Parameters: 

lines  name  Name  of  the  binary  GRASS  vector  (dig)  file,  imported  from  DXF  format,  that 

contaias  index  contour  lines. 

labels  ==««me  Name  of  the  binary  GRASS  vector  (dig_att)  file,  imported  from  DXF  format,  that 

contains  index  contour  line  labels. 


NOTES 

Because  line  data  that  are  created  in  CAD  format  may  have  unsnapped  nodes  or  gaps,  v.cadlabel  w  ill 
not  always  be  able  to  label  every  index  contour  line.  A  so,  intermediate  contour  lines  tliat  may  lie 
contained  in  the  index  contour  vector  file  (because  they  resided  on  the  same  DXF  level  as  the  index 
contour  lines  in  the  DXF  design  file)  will  not  be  labeled.  Aiv  lines  that  are  not  labeled  with 
v.cadlabel  can  be  labeled  with  the  contour  labeling  program  in  v.digit. 

If  the  intermediate  contour  lines  are  in  a  separate  GRASS  dig  file,  they  can  be  patched  to  an  labeled 
index  contour  file  with  the  GRASS  program  v.patch,  and  then  labeled  in  v.digit. 

The  user  does  not  need  to  v.patch  the  labels  vector  file  (boxes)  to  the  lines  vector  file  (contour  lines). 
Ihe  purpose  of  the  labels  vector  file  is  to  determine  which  labels  should  be  assigned  to  which  conic  hit 
lines  (in  the  lines  vector  file)  during  the  execution  of  v.cadlabel. 

SEE  ALSO 

v.digit,  v.in.ascii,  v.in.dxf,  v.out.dxf,  v.patch  and  dxfout  (Microstation  tool) 

AUTHOR 

David  Gerdes,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

v.clean  -  Cleans  out  dead  lines  in  GRASS  vector  files. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.clean 
v.clean  help 
v.clean  map =name 

DESCRIPTION 

When  programs  like  digit  delete  lines,  they  do  not  really  go  away,  but  are  simply  marked  as  deleted. 
Iliis  is  done  primarily  for  speed.  But  a  side  effect  is  that  vector  files  can  end  up  carrying  a  lot  of  dead 
weight  with  them. 

v.clean  will  go  through  a  vector  file  and  remove  all  dead  lines  in  the  file  thus  potentially  reducing  the 
size  of  the  file. 

You  do  not  have  to  run  v. support  afterwards. 


COMMAND  LINE  OPTIONS 
Parameter: 

map  Name  of  the  GRASS  vector  file  to  be  cleaned. 

BUOS 

None  known. 

SEE  ALSO 

i  .digit,  v. support 

AUTHOR 

Dnvicl  Cierdes,  U.S.  Army  Construction  Engineering  Research  Ialxiratory 
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NAME 

v.db.rim  -  RIM  data  base  manag ement/query  interface  for  GRASS  vector 
(GRASS  Vector  Program) 

SYNOPSIS 

v.dbj-im 

v.dbxim  datajbase 
OVERVIEW 

v.db.rim  allows  users  to  create,  manage,  and  query  information  about  labeled  lines  and  areas  from  a 
number  of  different  vector  maps  in  a  batch  mode  or  interactively.  Operations  are  done  on  a  data  base 
through  a  command  language  defined  in  section  one  or  through  an  interactive  set  of  menus  described  in 
section  two. 

Ihis  program,  like  s.db.rim,  is  actually  a  marriage  of  the  GRASS  environment  and  the  programmer  s 
interface  library'  of  the  relational  data  base  management  program  RIM  distributed  publically  by  the 
University  of  Washington  Academic  Computing  Services.  Your  sy  stem  mast  have  a  FORTRAN  77 
compiler  to  use  this  program. 

DESCRIPTION 

ihe  vector  data  bases  rce  stored  in  a  subdirectory  named  ’rim/vect’  in  the  user’s  current  mapset.  Data 
bases  in  other  mapsets,  selectable  through  the  GRASS  g  mapsets  command,  can  be  accessed  for  ’read¬ 
only’  retrieval  of  records.  Each  mapset  may  have  many  data  bases.  Each  data  base  within  a  mapset 
must  have  a  different  name;  user  supplied  names  are  limited  to  seven  (7)  characters  in  order  to  maintain 
compatibility  with  the  standard  version  of  RIM.  As  with  other  GRASS  commands,  mapsets  are 
searched  in  the  mapset  SEARCI LPATH  order  when  a  data  base  needs  to  be  opened. 

Each  vector  data  base  is  composed  of  multi  field  records  (rows  or  tuples,  in  DBMS  jargon).  Each  field 
and  its  position  in  the  record  form  is  defined  via  input  to  the  make  command  when  a  data  base  is 
originally  defined.  It  is  possible  to  add  new  fields  or  change  the  length  of  existing  fields  alter  data  has 
been  loaded,  however  this  is  not  straightforward;  deleting  of  fields  is  also  possible,  but  requires  even 
more  experience  and  knowledge.  The  user  needs  to  carefully  design  the  data  base  fields  and  form 
(layout)  and  check  the  operation  with  a  few  pieces  of  test  data  before  loading  data  for  a  large  number 
of  records. 

One  significant  difference  between  v.db.rim  and  s.db.rim  is  that  v.db.rim  needs  access  to  the  original 
vector  maps  that  data  were  imported  from  to  successfully  complete  some  commands.  To  keep  track  of 
which  records  were  imported  from  which  vector  maps,  a  new  "table"  has  been  added  that  keeps 
informal  .  the  reference  vector  maps.  This  table  is  called  "Referencemaps"  in  the  RIM  data 
base.  The  v.dbjim  commands  ,read_vect,  .map  and  maps  allow  the  user  to  view  and  update  this  table. 
Ihe  ,vector_map  command,  which  creates  a  new  GRASS  binary'  vector  file,  requires  that  the  reference 
vector  maps  for  the  data  base  be  accessible  If  a  reference  map  is  not  accessible,  any  vectors 
represented  by  the  data  base  records  that  were  generated  from  that  vector  map  will  not  be  transferred  to 
a  new  vector  map.  Reference  vector  maps  may  be  in  any  mapset  in  the  current  SEARCHJ’ATIL 

SECTION  ONE  -  THE  COMMAND  VERSION 

(No..:  For  each  of  the  "dot  commands,"  eg.,  .make,  described  below  there  is  a  menu  choice  to  select 
when  running  the  interactive  version.  The  interactive  menus  are  described  in  section  two  of  this 
document.  Some  display  capabilities  exist  in  the  interactive  version  that  are  not  directly  implemented 
in  the  command  version.) 

The  commands  are  given  alphabetically  here  for  easy  reference.  The  .make  command  is  required  to 
create  a  data  base.  Abbreviations  down  to  the  string  shown  in  (  )  are  accepted;  this  is  primarily  for 
those  giving  v.db.rim  commands  from  a  terminal,  but  abbreviations  may  also  be  used  in  batch  files. 

Each  command  is  introduced  with  an  input  record  (line)  that  starts  with  a  period  and  is  followed  by  one 
of  the  words  shown  below;  for  some  commands  the  command  line  also  contains  one  or  more  required 
or  optional  parameters.  Additional  or  optional  input  iastmetioas/data  for  a  command  is  supplied  on 
successive  lines;  a  .end  line  is  needed  by  some  commands  to  signify  the  end  of  these  lines. 
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Alphabetical  Command  Summary 

'.command. 

This  is  the  only  v.db.rim  command  not  starting  with  a  period,  "command”  is  a  single  shell 
command  line  (no  more  than  80  characters)  that  is  executed  by  a  "G_systemO"  call  (see 
GRASS  gis  library).  Many  UNIX  utilities  (eg.,  vi,  Is,  print)  and  most  GRASS  commands 
(eg.,  d.rast,  d.sites,  gJist,  g.region,  r.mask)  may  be  executed.  It  is  permitted,  and  often  useful, 
to  change  "region"  and  "MASK"  within  v.db.rim.  Multiple  commands  may  be  separated  by 
in  the  standard  UNIX  way.  Note  that  a  "!cd  directory;  Is"  will  change  to  the  specified 
directory  and  list  files,  but  the  effective  working  directory  for  v.db.rim  will  not  be  changed 
when  the  command  terminates. 

.add  (.a) 

Add  a  new  vector  record  (row)  to  the  open  data  base.  Each  line  following  contains  a  field 
name  followed  by  spaces  and/or  tabs,  then  the  value  or  character  string  to  store  for  that  field. 
Field  information  lines  end  with  .end.  Some  fields  may  be  absent  and  fields  may  appear  in  any 
order.  The  input  of  data  is  checked  for  one  required  field  (sequence  number),  for  field  length 
for  text  type  fields,  and  for  duplicate  sequence  numbers.  If  split  text  fields  are  used  in  the  data 
base  lay  out  (see  .make),  text  data  for  each  split  field  must  be  added  as  a  separate  line.  If  there 
are  any  problems,  the  record  will  not  be  stored  and  a  message  will  be  output.  This  format 
makes  it  relatively  easy  to  import  data  from  most  other  DBMS.  The  ".print  -a"  command,  see 
below,  outputs  data  in  this  list  format. 


Example : 
add 

seq_num  204 
north  469067330 
east  601410.00 
map_num  1 
vect_type  L 
reference  Jones  (1987) 

.end 

.backup  (. b )  file  name 

The  .backup  command  is  used  to  dump  the  entire  data  base  from  the  RIM  binary  files  to  a  text 
file  format  (see  UNIX) AD  in  the  RIM  User’s  Manual).  The  file_name  can  be  a  relative  path 
name  or  full  path  name.  The  file  will  contain  the  data  base  definition,  screen  layout 
information,  and  tabular  data.  This  text  file  is  transportable  to  RIM  or  v.db.rim  running  on 
any  other  computer;  it  may  also  be  reloaded  to  recreate  the  v.db.rim  data  base.  A  message 
will  be  output  if  there  is  any  problem  writing  the  .backup  file.  Backup  can  only  be  done  on 
data  bases  in  the  user’s  current  mapset. 

To  reload  your  data  base  from  the  backup  file  (normally  not  necessary): 


GRASS  4>cd  SIXICATION/rim/vect 
GRASS  4>rm  db_namejiindb* 
GRASS  4>rim 
RIM>  input  "path/file" 

RIM>exit 


#  right  directory 

#  remove  data  base 
#run  RIM  manually 

#RIM  rebuilds  data  base  from  data 
written  by  backup 


change  (.c)  /  -/  / 

Without  the  "1”  flag,  each  line  following  .change  is  in  the  same  format  as  fix  the  .add 
command,  lhe  sequence  number  field  is  required  and  the  sequence  number  must  match  an 
existing  site  in  the  data  base.  Only  those  fields  for  which  lines  are  provided  are  changed  in  the 
record.  After  the  .end  the  ch;mged  reecxd  is  stored,  if  .ill  is  ok;  otherwise,  a  message  is  output. 
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If  the  "-1"  flag  (for  "list")  is  given,  the  sequence  number  held  is  omitted  and  the  specified  held 
values  are  changed  in  all  records  currently  selected  by  iind  and/or  .query. 

.delete  (.d ) 

This  command  is  used  to  delete  data  records.  Deletion  of  records  is  permanent.  Each  line 
following  the  command  should  contain  only  a  sequence  number  that  you  want  to  delete,  with  a 
.end  line  being  last. 

A  backup  of  the  data  base  or  copies  of  the  data  base  files  are  the  ways  to  protect  your  valuable  data. 
The  following  command  sequence  will  delete  all  the  records  currently  on  v.dbjim’s  query  list  (the 
result  of  the  last  .query  or  iind  command),  after  asking  for  approval. 

.delete 

.end 

.end  (.e) 

Ends  multi-line  input  for  several  other  commands. 

.exit  (.ex) 

Use  .exit  to  end  operation  of  v.db.rim  cleanly,  hi  general,  do  not  use  CTRL-C  to  exit  unless 
absolutely  necessary.  When  .exit  is  encountered  in  a  batch  file,  input  will  revert  back  to  the 
previous  file,  or  the  terminal,  if  any,  that  called  the  batch  file. 

.find  (.f)  l-m  |  -wj  [  a  |  -d] 

The  .find  command  is  used  to  find  the  record(s)  whose  location  (label  point)  is  closest  to  a 
given  point  (the  target).  The  target  can  be  defined  in  one  of  several  ways.  The  found  records 
are  stored  on  an  internal  query  list  for  output  by  other  commands;  however,  see  note  2,  below. 
Records  are  stored  on  the  query  list  in  order  of  proximity  to  the  target  location.  The  optional 
find  command  line  parameter  specifies  the  current  MASK  (  in),  if  any,  or  the  current  region  (- 
w),  as  a  filter  on  the  retrieved  records;  see  notes  3  and  4,  below.  The  append  (  a)  or  delete  (d) 
options  allow  the  "found"  records  to  be  added  or  deleted  from  the  currently  selected  ones. 
When  adding,  duplicates  will  be  discarded. 

The  single  required  line  following  the  find  line  gives  the  program  the  necessary  target  information. 
The  following  examples  show  the  possibilities. 

find> 602793 .90  4379010.00 

will  find  the  one  record  nearest  these  coordinates  and  store  it,  append  it  or  delete  it  cm  the  internal  query  list. 
find>  619840  4599000  10 

will  find  the  10  records  (or  fewer,  if  there  are  not  that  many)  closest  to  the  given  location. 
find>  record  132  10 

will  find  the  10  records  closest  to  the  location  (label  point)  for  record  132  in  the  data  base  (including 
record  132).  If  record  132  does  not  exist,  no  action  is  taken. 

find>  distance  from  472910.06  5732001.0  5000 

will  find  all  records  within  5000  (meters  in  U1M  ccxirdinates)  of  the  target  fixation. 

find>  distance  from  record  16  -2500 

will  find  all  records  greater  than  2500  (meters)  from  the  location  of  record  16. 
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Notes  for  .find: 

1.  All  records  found  by  each  .find  are  stored  cm  the  query  list  in  order  of  proximity  to  the  target 
location  (sotted  by  distance  from  target). 

2.  The  number  of  records  found  is  automatically  printed  to  the  active  output  device/file. 

3.  If  mask  is  specified,  the  effective  region  is  automatically  set  to  the  current  region  (because  the 
GRASS  mask  is  only  defined  for  the  current  region). 

4.  Region  and  mask  filtering  uses  the  current  resolution  for  the  region  to  test  if  a  point  falls  within  a 
cell. 

5.  In  the  last  two  examples  the  string  "distance  from"  must  be  exactly  matched.  Also,  the  word 
"record"  must  be  exactly  matched. 

6.  If  the  "distance  from"  radius  is  given  as  a  negative  value,  points  outside  the  target  circle  are 
selected;  whereas,  if  a  positive  value  is  given,  points  inside  the  circle  are  selected. 

7.  The  current  region  may  be  changed  with  !g. region  or  !d.zooin  prior  to  doing  a  find,  and  the  mask 
may  be  set  or  removed  with  a  variety  of  GRASS  commands. 

8.  Ihe  "find:>  prompt  is  given  only  when  input  is  from  a  terminal. 

9.  The  "distance"  between  the  target  location  and  a  record  for  a  line  or  an  area  is  actually  the  distance 
between  the  target  location  and  the  representative  point  that  is  stored  in  the  data  base.  This  can  lead  to 
unexpected  results  when  the  representative  point  (label  point)  for  a  line  or  area  is  not  near  the  "center'' 
erf  the  feature. 

help  (.h) 

Prints  a  help  screen  to  the  output  device  or  file.  Useful  to  have  when  using  v.dbsim  from 
terminal,  or  when  writir^;  a  script  file  of  commands. 

.input  (.i)  [file] 

The  lines  in  the  given  file  are  read  and  processed  as  commands  or  data  until  an  end  of  file  is 
reached  or  until  a  .exit  command  is  found.  Input  files  may  call  other  input  files,  by  using  this 
command,  to  a  nesting  depth  of  eight.  Without  a  file  name  stdin  is  used  as  the  input  file. 

.list  (.1) 

lists  the  available  data  bases  in  the  current  mapset  search  path. 

.make  Using  the  .make  command  y  ou  create  a  new  data  base  in  the  current  mapset  by  specifying  the 
folkwing  items  that  define  the  screen  (page)  layout  for  displaying  and  printing  the  records,  as 
well  as  the  information  fields: 

1)  The  fixed  text  part  of  die  screen  layout. 

2)  The  positions,  types,  and  lengths  of  data  fields. 


live  fields  must  always  exist  in  a  data  base;  each  of  these  field  types  may  only  occur  once  in  a 
data  base  layout: 

1)  Type  ’s’  Sequence  number  field  (a  unique  integer  for  each  record). 

2)  Type  ’x’  Pasting  coordinate  of  the  representative  point  (a  double  float). 

3)  Type  V  Northing  coordinate  erf  the  representative  point  (a  double  float V 

4)  Type  V  Vector  type  field  (a  text  field). 

5)  Type  ’m’  Reference  Map  field  (an  integer). 
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The  other  field  types,  which  may  occur  in  any  combination  and  order,  are: 


6)  Type  ’i’ 

An  integer  field. 

7)  Type  ’f 

A  double  precision  float  field. 

(always  2  decimal  places  used  for  output) 

8)  Type  T 

A  text  field. 

Each  of  the  fields  can  be  positioned  anywhere  within  the  screen  layout,  which  has  a  limit  of  19  lines  by 
80  columns.  A  maximum  of  70  fields  may  be  defined  within  this  space.  A  field  is  specified  in  the 
screen  layout  by  a  tilde  (*),  a  field  type  character,  a  field  name  and  enough  trailing  tildes  to  fill  out  the 
desired  field  length. 

Each  line  following  the  .make  command  is  taken  to  define  a  line  of  the  screen  layout  until  a  .end  is 
reached.  If  a  mistake  is  made  on  any  of  the  input  lines,  the  .make  will  fail.  The  make  information 
may  be  prepared  in  advance  as  a  text  file  (this  facilitates  fixing  mistakes)  and  the  .input  command  can 
be  used  to  read  in  this  file.  An  example  text  file  for  a  data  base  screen  layout  follows,  with  some 
explanatory  notes  and  restrictions. 

.make 

Ffydrology  Vector  Ehtabase 


Record  'sSeqnurf  Feature  Name:  '  tName . 

Vector  type:  "vVtype  Reference  Map:  'nRefNfep' 

North:  'yNorth  East:  'xEast . 

Ejxlated:  *  tLJodateJiite 

Garments : 

"  tCannents  .1  . 

*  tCcnments  .2  .  . 

*  tCcnments  .3  .  . 

.end 

Notes: 

1)  Any  text  not  preceded  by  a  tilde  (')  character  is  taken  to  be  part  of  the  constant  or  fixed  text 
portion  of  the  form. 

2)  A  field  definition  begins  with  a  tilde  (* )  character  immediately  followed  by  a  single  character  that 
indicates  the  data  type  of  the  field  (spt,y,vrnj,f  or  t).  Immediately  following  the  data  type  character  is 
the  field  name  of  1  to  16  characters.  Field  names  can  Ire  composed  of  any  characters  from  the 
following  set:  [A-Z^-zv_J[)'9j;  the  RIM  program  and  library  do  not  distinguish  upper  and  lower  case  in 
field  names,  so  you  should  avoid  making  names  which  differ  only  in  case.  Field  names  may  not  begin 
with  a  numeral  [0-9] .  The  rest  of  the  field  length  is  padded  with  tilde  (')  characters  to  the  length 
desired. 

3)  Ihe  minimum  field  width  is  three  characters;  eg.,  "~tA".  Be  sure  field  widths  for  all  fields  are  wide 
enough  for  the  values  and  strings  you  expect  to  store  there;  eg.,  UTM  northings  require  at  least  11 
spaces. 

4)  For  text  fields  it  is  possible  to  continue  a  field  across  more  than  oik-  line,  lhis  is  done  In 
appending  a  .1  to  the  field  name  firming  first  portum  of  this  "split  field,"  a  .2  fir  the  second  portion, 
etc  lhis  text  field  splitting  affects  how  information  is  trg.uiized  for  input  and  output;  the  composite 


GRASS  4.0  (Summer  1991) 


US.  Annv  (  1RJ 


376 


v.db.rim 


GRASS  Rclcrcncc  Manual 


v  .db.rim 


text  string  is  concatenated  (unused  portions  of  fields  are  retained  as  spaces)  ;uxl  treated  as  a  unit  for 
storage  and  queries  to  tite  data  base. 

.map  (.m)  /  map  .  id  map.  name  }  \  [  -d  mapJd  J 

Without  arguments  this  command  outputs  a  list  of  all  the  reference  vector  maps  that  are  stored 
in  the  reference  maps  table.  If  a  map  number  (map_id)  and  a  vector  map  name  (map_name) 
are  given  the  vector  imp  is  found  and  added  to  the  reference  maps  table  in  the  data  base.  If 
the  map  number  (id  tnim)  is  already  in  that  table  an  error  is  issued  and  no  action  is  taken. 

I  anal  ly .  to  delete  a  map  from  the  reference  maps  table,  use  the  ’-d’  option  followed  by  the  map 
nun il >er  (map  id).  Ihe  map  information  for  the  given  map  number  will  be  displayed  and  the 
user  will  be  asked  to  confirm  the  deletion  with  a  V .  I  nter  a  ’n’  (for  no)  if  you  do  not  w  ant  to 
delete  that  reference  map. 

Remember,  tliat  if  you  delete  a  reference  map  for  w  hich  there  are  still  records  in  the  data  base, 
you  cannot  make  a  new  vector  map  (using  the  vector  _  map  command)  that  includes  those 
records  unless  you  put  that  number  and  vector  map  name  back  in  the  reference  map  table. 

.output  (.o)  I  file  or  |  process  / 

Causes  all  output  (except  some  error  messages)  from  v.db.rim,  including  that  from  the  print 
command,  to  go  to  the  named  path/file  (may  be  a  full  or  relative  path  name),  or  to  be  used  as 
standard  input  by  the  process  (a  pipe).  If  no  parameter  is  given,  output  returns  to  stelout, 
usually  the  user's  terminal  An  example  of  the  pipe  usage  would  be 

.exit put  |  grep  "easting"  |wc  -1  >  Amp/my_axint 

A  pipe  is  closed  whenever  the  .output  command  is  given  again,  or  on  a  .exit  command. 

.pack  (.pa) 

This  should  lx:  used  when  nunxTixts  data  records  have  been  deleted  or  changed  to  recover  disk 
space  in  the  RIM  binary  data  base  files.  It  works  by  doing  a  backup  to  a  temporary  file; 
nxiving  tlie  data  base  Hies  to  new  names  (*.bakd!>);  running  RIM  to  rebuild  the  data  base’ 
and,  if  the  relxnlt  data  base  can  Ire  opened  and  read,  tlx:  temporary  files  are  deleted.  The  usei 
is  informed  if  this  process  f;iils.  Packing  can  only  be  done  on  an  open  data  base  fixated  in  the 
users  current  mapset. 

print  (  p)  l -a  |  -// 

This  command  ixitputs  the  full  record  for  the  records  currently  stored  on  the  internal  query  list 
(result  of  last  .query  or  .find).  Without  the  flag,  the  screen  layout  format  is  used.  With  the  I 
flag,  for  list  format,  the  field  minx'  followed  by  tlx:  contents  are  output  one  Held  per  line.  The 
a  flag  also  ixitjxits  in  die  list  format  but  with  a  add  line  and  a  .end  line  surrounding  each 
record  printed;  data  files  in  this  form  can  lx-  read  with  input,  thus  they  form  one  kind  of 
backup  inechanism  and  can  lx  used  to  transfer  data  (ix>t  the  data  base  layout)  from  one 
GRASS  system  to  another.  The  destination  for  the  output  is  set  by  a  previixts  .output 
axnmand  (delault  is  stekxit). 

query  (.q)  fm  \  -w)  fa  \  -d) 

Ihe  .query  commaixl  is  used  to  retrieve  records  v  ia  an  SOI -like  request  to  RIM.  including  a 
user  specified  "where  clause."  All  fields  for  each  record  nxxting  die  selcctfixi  criteria  .ire 
retrieved. 

The  optional  .query  command  line  panuncters  cause  records  whose  representative  points  .ire 
txrt  in  the  region  (  w )  aixl/or  mask  (  m)  to  be  rejected,  so  these  conditions  need  not  lx-  tested 
in  the  "where  clause*."  See  hud  for  a  full  explanation  of  the  oxTHTiand  line  options 

After  the  query  command  line,  am  numlx'r  of  lines  (each  ixi  nxxe  dian  80  characters!  in.iv  b>- 
entered  to  ilelme  llu  SOI  "where"  clause  A  end  line  is  required  to  finish  tlx  request  aixl 
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begin  data  retrieval.  See  examples  below. 

The  "distance  from"  clause  may  also  be  used  as  an  additional  selection  criteria  exactly  as 
described  in  the  examples  and  notes  for  .find.  It  must  be  entered  as  a  separate  line  to  the 
query  prompt. 

The  retrieved  records  may  be  printed  at  time  of  retrieval,  rather  than  after  the  completion  of 
the  query  command  by  including  a  .pint  (.p)  line  with  the  same  options  for  print  format  as  in 
the  .print  command  (see  above);  eg.,  .p  -a  to  output  in  the  "list  add"  format.  The  .print  clause 
must  be  entered  as  a  separate  line  to  the  query  prompt.  This  feature  is  most  useful  when 
working  with  very  large  data  bases  where  retreval  time  is  significant.  See  example  2  below. 

Example  1 

query>where  density  <20  and  (date  =  "10/14/89" 
query  >  or  county  eq  "San  Marcos") 
query  >. end 

Example  2 

query > where  east  <600000  and  name  like  "* Jones*" 
query  >  distance  from  record  12  3000 
query >. print  -a 
query  >. end 

Example  3 

query  >.end 

The  where  and  distance  from  clauses  are  each  optional.  If  both  are  omitted,  only  the  mask  and 
region  on  the  .query  command  line  restrict  the  search;  if  mask  and  region  are  also  omitted,  all 
records  will  be  retrieved  (Example  3).  When  querying  for  records  the  where  clause  is 
processed  first,  the  current  region  and  mask  tested  (if  requested),  then  the  distance  from  clause 
is  applied;  a  record  must  pass  all  tests  to  be  put  an  the  internal  query  list  (or  appended  or 
deleted)  for  output  by  other  commands. 

Notes:  (Also  see  Notes  for  find) 

1.  The  retrieved  records  are  stored  on  the  internal  query  list  in  the  order  returned  from  the 
data  base  by  RIM,  not  necessarily  in  sequence  number  order  or  the  order  the  data  was  loaded. 
A  "distance  from"  clause  results  in  a  final  sorting  by  proximity  to  the  target. 

2.  See  the  RIM  User's  Manual  and  the  s.db.rim  manual  page  for  additional  information  on 
the  "where  clause"  in  the  "select”  command,  especially  the  quotas  required  for  matching 
character  string  (text)  fields,  and  the  alloved  comparison  operators.  (These  are  also  described 
in  section  two  of  this  manual  entry.) 

3.  In  the  example  where  clauses  above,  "density",  "date",  "county”,  east”,  and  "name"  are  field 
names  (column  names  in  RIM)  defined  when  the  user  initially  makes  the  data  base. 

4.  Each  .query  or  .find  resets  the  interna)  query  list,  unless  the  append  or  delete  options  are 
used.  In  no  case  is  a  record  allowed  to  be  duplicated  on  the  query  list. 
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,read_vect  (.re)  vector _jnap_name  [attribute-field  [ text -field J[ 

This  command  will  read  an  existing  GRASS  vector  map  and  create  a  data  base  record  for  each 
labelled  area,  line,  and  point.  The  sequence  number  held  will  automatically  be  generated 
starting  from  one  greater  than  the  highest  current  number  in  the  data  base.  If  the  optional 
attribute _field  is  provided  it  must  be  an  integer  held  and  it  will  be  filled  with  the  area,  line,  or 
point  attribute  label.  If  the  optional  text-field  is  provided  and  a  category  description  hie  (a 
<£g_cats  hie)  exists  for  the  vector  map,  the  category  descriptions  will  be  copied  into  the  given 
text  held. 

Once  the  records  have  been  loaded  by  .read_vect,  use  .change  to  add  data  to  other  helds  for 
those  records. 

Note:  Only  labeled  areas,  lines  and  points  are  imported  from  the  vector  map. 

.remove 

This  command,  which  requires  a  "y”  as  confirmation  on  the  next  line,  entirely  removes  the 
three  binary  files  which  constitute  your  RIM  data  base.  Use  with  care.  Backup  hies  must  be 
removed  individually  by  the  user,  if  desired. 

show  (.sh) 

This  command  is  used  to  output  the  screen  or  page  layout  as  defined  for  the  current  data  base. 
It  serves  as  documentation  of  the  data  base  definition  and  as  a  reminder  for  held  names,  types 
and  lengths.  By  using  an  editor  to  surround  the  ixitput  of  -show  with  make  and  .end  lines,  it 
can  be  used  to  reload  the  data  base  definition  with  input. 

site  Jist  (si)  file_name  [field-name] 

This  command  writes  the  location  coordinates  (representative  point)  and  a  comment  to  the 
specified  hie  in  the  sitejist  directory  in  the  current  mapset  for  each  record  currently  selected. 
If  the  site  file  exists,  the  sites  are  appended  to  the  current  list,  otherwise,  a  new  ate  list  hie  is 
created.  A  "held  name"  may  be  optionally  specified;  if  so,  the  contents  of  that  held  (retrieved 
from  the  appropriate  site  record)  are  inserted  as  the  comment  (following  a  'if)  in  the  site  list; 
the  record  number  is  used  if  no  held  name  is  given.  Such  site  lists  may  be  used  as  input  t< 
s.db.rim. 

A  comment  line  is  inserted  in  the  sitejist  hie  with  the  current  date  and  time  and  the  name  of 
the  data  base  producing  the  site  locations.  The  format  used  for  each  site  is: 

easting  |  northing  |  dumber  or  comment 


.tables  (. t ) 

Prints  the  table  structure  of  the  currently  opened  RIM  data  base.  This  is  the  same  output 
generated  by  a  "list  *"  command  when  running  RIM  manually.  The  information  for  the  table 
named  data"  is  useful  for  review  of  the  user’s  held  definitions,  and  the  table  named 
"Referenceinaps"  contains  the  reference  map  information.  The  information  in  the  two  other 
tables  is  for  internal  use  by  v.db.rim. 

.vector-map  f.v)  file_name  [attribute -field  [text -field]] 

This  command  creates  a  new  binary  vector  map  by  copying  the  vectors  associated  with  each 
record  on  the  query  list  from  the  reference  vector  maps  into  the  new  vector  map. 

If  the  optional  attribute -field  parameter  is  provided,  the  areas  and  lines  in  the  new  vector  map 
will  lx-  I.ilvled  from  the  given  integer  (i,  ni,  or  s  type)  held  value  for  each  record.  You  may 
supply  a  fixed  integer  value  (such  as  1, 908,  7,  etc.)  instead  of  a  field  nunc;  each  line  written 
to  the  new  map  will  be  given  this  constant  attribute/label. 
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If  the  optional  text_field  is  provided,  it  will  be  used  to  build  a  category  description  file 
(dig_cats  file)  for  the  vector  map.  Instead  of  a  field  name,  a  constant  text  string  of  up  to  100 
characters  may  be  given,  if  enclosed  in  single  or  double  quotes;  this  string  is  used  as  the 
category'  description  for  each  line  written  to  the  new  vector  file. 

The  header  of  the  new  binary  vector  file  will  contain  the  current  date  and  indicate  that 
v.db.rim  was  used  to  create  the  vector  map. 

The  topology  information  (the  dig_plus  file)  is  not  automatically  built  for  the  new  vector  map 
and  the  user  must  run  support. vect  to  do  so  before  v. digit  can  be  used  to  edit  the  vector  map 
or  some  other  programs  can  be  used.  The  vector  map  can  immediately  be  displayed,  from 
within  v.db.rim  by  issuing  the  following  command  (assuming  you  have  a  graphics  monitor 
selected): 

Id.vect  file_name  c=color 
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SECTION  TWO  -  THE  INTERACTIVE  VERSION 
SYNOPSIS 

v.db.rim 

DESCRIPTION 

When  run  interactively,  v.db.rim  allows  you  to  create,  manage  and  query  information  about  vectors 
across  the  landscape  on  a  data  base  through  the  series  of  menus  (VASK  screens)  explained  below. 

THE  MAIN  MENU 

Below  is  the  main  menu.  Option  1  is  the  default.  Note  the  status  line  at  the  top  of  the  menu,  and  the 
fact  that  8  records  have  been  selected  by  the  last  find  or  query  operation  (between  items  2  and  3). 
Note,  also,  that  ( TR1 ,-C  can  be  used  to  exit  from  this  menu  (and  most  other  menus  in  the  program) 
Ixick  to  the  GRASS  prompt.  Ihe  specifics  of  each  menu  choice  are  described  below,  Except  for  6,  and 
mouse  options  in  3  and  4,  each  choice  has  a  direct  counterpart  in  the  command  version. 

v.db.rim  MAIN  MENU  Version  1.4 

IXita  base  <i',vers  >in  mapset  <kittco  >open.  325  records. 

1  <  )|x:n  a  Gita  base 

2  1 1st  available  vector  data  bases 

-  Retrieve/(  Xitput  Site  Records  (8  currently)  -- 

3  find  records  in  proximity  to  a  Target  point 

4  (>icry  to  select  records  (SOL) 

5  Show  selected  records  on  Terminal 

6  Display  maps/selected  vectors  on  graphics  terminal 

7  (Xitput  selected  records  to  Printer  or  File 

8  Create  vector/site  maps  from  selected  records 

Ald/Ldit  Site  Records  . 

9  View  a  single  record 

10  Aid  a  record 

11  Change  a  record 

12  Delete  a  single  record  or  all  selected  records 

Other  functions  --  Shell  Command  -  Beit  - . - 

1 3  M;ike  a  new  data  base  &  Management  1 -unctions 

14  Execute  a  shell  command 
0  IX>ne  Exit  from  v.db.rim 

AETER  COMPUTING  AIJ.  ANSWERS,  IDT  <F,SOTO  CONTINUE 

(or  <Qri-c>'io  exit  Tins  program) 


1.  Open  a  dita  base.  If  a  dita  base  is  already  open,  it  is  closed  before  the  requested  one  is  opened. 
Only  dita  bases  in  the  user’s  current  mapset  may  be  modified;  others  are  opened  in  read-only  mode; 
this  will  lx-  indicated  on  line  2  of  the  menu. 

2.  list  availaNe  data  bases.  For  each  mapset  in  the  current  (iRASS  mapset  search  path,  the  names  of 
the  existing  vector  tlala  bases  arc  listed. 

3.  "I -1  inf  records  in  the  dita  base  relative  to  a  specified  target  fixation.  'Ibis  is  used  to  select  records 
lxis(d  on  proximilx  to  the  target  and,  optionally,  reeords  within  the  current  region  and,  optionally, 
records  f.tlliii"  in  active  cells  within  the  current  GRASS  mask.  Ihe  label  point  coordinates  are  used  for 
these  spatial  tests.  Two  modes  of  targeting  ;ire  provided:  the  N  records  closest  to  the  target,  and  all 
tec  on  Is  within  (or  outside)  a  circle  of  specified  radius  from  the  target.  'Ihe  IIND/QLTRY  TARGET 
MINI  discussed  Ivfim  accepts  rig  ion/mask/target  specifications  from  tlx-  user,  The  selected  records 
arc  then  display  i  d  one  at  a  time  until  CIKE-C  is  entered;  then  other  operations,  choices  5  S  can  ■  e 
done  with  these  records.  Ihe  line  on  the  menu  Ixtwecn  2  arxi  3  shows  the  munlxr  of  records  current! \ 
selected  bv  choices  3  or  4. 
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4.  "Query"  records  in  the  data  base  using  an  SQElike  "where  clause,"  including  specifications  for 
reg  ion/mask/taiget  (circle  only)  as  in  3,  above;  see  FTNDkQUERY  TARGET  MENU  section  below. 
The  where  clause  can  test  for  ranges  or  matches  for  numeric  data  base  fields,  or  matches  on  full  strings 
or  substrings  for  text  fields.  The  selected  records  are  then  displayed  one  at  a  time  until  CTRL-C  is 
entered;  then  other  operations,  choices  5-8,  can  be  done  with  these  records.  This  clause  is  entered  on  a 
QUERY  COMMAND  MENU  described  below. 

The  where  clause  may  use  parentheses  (  )  to  control  the  order  of  comparisons.  Held  names  are  not 
case  sensitive  within  where  clauses.  The  following  comparison  operators  are  valid  for  all  types  of 
fields: 

eq  or  =  ne  or  o 

ge  or  >=  le  or  <= 

gt  or  >  It  or  < 

String  comparisons  are  case  sensitive  and  are  done  character  by  character.  Substrings  comparisons  may 
be  done  with  the  "like"  operator  as  in: 

where  name  like  "*Jones*" 

Note  that  the  string  being  tested  against  the  name  field  for  each  record  is  in  quotes  (single  or  double) 
and  that  wild  card  comparisons  can  be  done  in  the  standard  way  with  and  ’?  characters. 

Logical  comparisons  may  also  be  combined  with  those  operators  above.  The  permitted  logical 
operators  are: 

and  or  not 

The  following  complex  example  should  be  examined.  The  line  breaks  can  occur  between  any  tokens 
(words,  values,  operators),  except  within  quoted  strings. 

where  (name  like  "*  Jones*"  or  name  =  "Smith”) 
and  (  (  site  <300  and  not  (site  =  251  or  site  eq  15)  ) 
or  east  <601000  ) 

5.  This  choice  will  display  the  records  resulting  from  the  last  find/query  one  at  a  time  on  the  terminal. 
Use  ESC  or  enter  a  number  to  display  another  record  and  CTREC  to  end  the  display. 

6.  If  a  graphics  monitor  is  active,  the  selected  vectors  will  be  displayed.  The  user  may  choose  to  erase 
the  screen;  display  raster,  vector,  and/or  site  maps;  and/or  display  the  selected  vectors  from  the  data 
base;  these  maps  are  requested  through  the  following  interactive  screen.  Just  enter  ESC  to  skip  this 
step.  If  no  data  base  vectors  are  currently  selected,  that  section  of  the  menu  will  not  appear;  but  the 
menu  can  still  be  used  to  display  the  other  types  of  maps. 
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SELECHON  MENU  FOR  HEMS  TO  DISPIAY 

Enter  raster  and/or  vector  map  names,  if  desired 

_  Raster  file  to  display 

_  Vector  file  to  display  in  color: _ 

_____  Site  list  to  display 

Dpoints  with:  size=3_  type=box _ color=white 

_  Display  currently  selected  vectors  (enter  x) 

LVect  red _ 

_  Erase  graphics  screen  (enter  x) 

Denise  black _ 


AEIER  COMPILING  ALL  ANSWERS,  HIT  <ESC>  TO  CXINITNUE 
(OR  <Ctrl-C>TO  CANCEL) 


7.  This  selection  results  in  a  screen  prompting  for  the  name  of  the  file  to  output  the  selected  records  to, 
and  for  optional  formatting  selection.  If  the  file  name  is  lp,  the  site  records  are  sent  to  the  printer.  The 
optional  formatting  choices  are  for  export  of  data  in  list  and  add  formats;  see  the  print  description  in 
section  one  of  this  manual  page  for  information  and  examples. 

8.  Using  this  choice  you  can  create  a  new  GRASS  vector  map  consisting  of  the  vectors  for  the 
currently  selected  records,  and/or  a  site  list  consisting  of  the  representative  points  (label  points)  for  the 
currently  selected  records,  in  your  current  mapset.  A  short  menu  prompts  for  the  map  names  and  other 
information. 

If  a  vector  map  name  is  given  you  can  choose  an  integer  field  (i,  s,  or  m  types),  or  a  fixed  value,  to 
write  as  the  label  value  for  each  vector  in  the  dig_att  file  for  the  new  map.  You  may  also  specify  a 
field  name  (any  type),  or  a  fixed  text  string  in  single  or  double  quotes,  to  write  as  the  categoiy 
description  in  the  dig_cats  file  for  the  new  map. 

If  ycxi  give  a  site  list  name,  you  can  specify  the  name  of  a  field  (or  fixed  text  string  in  quotes)  to  be 
used  for  the  "Comment"  in  the  site  list  (the  record  number  is  the  default  field).  The  current  date  and 
time,  and  the  names  of  the  mapset  and  data  base  in  use  are  entered  as  an  information  line  in  the 
sitejist  file.  Note  that  you  can  create  a  new  site  list  or  append  to  an  existing  site  list,  or  both. 

A  variety  of  raster  maps  can  be  produced  from  a  v.do.rim  data  base  by  creating  new  vector  files,  then 
using  the  v.to.rast  program,  and  by  writing  sitejists  with  different  fields  as  "comments,"  then 
converting  the  sitejists  to  raster  maps  with  s.menu. 

9.  Choices  9-12  operate  on  only  a  single  record  and  do  not  use  or  modify  the  internal  list  of  records 
selected  by  lind/quciy  (choices  3  or  4).  Choice  9  is  the  way  to  view  a  single  record,  selected  by  record 
number.  After  viewing,  ESC  will  allow  entry  of  another  site  number  and  CTRDC  will  exit  to  the  main 
menu. 

10.  Use  this  selection  to  add  a  new  record  to  the  data  base.  (A  new  record  is  one  whose  numlxT  docs 
not  currently  exist  in  the  open  data  base.)  After  making  this  selection,  the  data  base  layout  will  be 
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displayed  and  you  should  enter  the  available  information  appropriate  to  each  field;  lire  only  required 
entry  is  the  site  (record)  number  field.  If  values  for  numeric  fields  are  not  entered,  zero  values  will  be 
stored.  Unused  portions  of  text  fields  are  stored  as  strings  of  spaces. 

11.  After  making  this  selection  uxl  specifying  the  record  number  to  change  field  information  for,  the 
data  is  entered  as  for  choice  10.  except  that  the  record  number  cannot  be  changed.  (  Ihe  command 
version  of  the  program  has  provision  for  making  bulk  changes  after  a  find  or  query  ;  see  .change.) 

12.  To  delete  a  single  record,  enter  its  number  when  requested.  All  records  chosen  by  the  last 
find/query  operation  may  be  deleted  by  entering  "list"  in  place  of  the  record  number.  Bli  (  AR1TU1 . 
with  this,  deleted  records  are  really  gone. 

13.  This  choice  starts  a  new  menu  with  less  commonly  used  functions.  See  MANAGIMhNT  MIvNU 
section  below. 

14.  The  program  will  prompt  you  for  one-line  Shell  Commands  until  you  enter  just  a  <R1'11Ji<N>  to 
return  to  the  main  menu. 

KINDAJUERY  TARGET  MENU 

litis  is  the  screen  to  set  up  the  reg i onAnas k'targ et  information  for  the  find  choice  (3)  and  the  query 
choice  (4),  except  that  item  B  is  omitted  for  choice  (4).  If  a  graphics  monitor  is  not  active,  the 
"mouse"  item  is  omitted  from  the  menu;  and,  if  a  mask  is  not  currently  set,  that  line  is  omitted. 

Ihe  choice  to  append  or  delete  the  selected  records  w  ill  only  be  given  after  a  successful  find  or  query 
has  stored  some  records  on  the  internal  record  list.  When  appending  records,  duplicates  of  those 
previously  selected  will  be  discorded -they  will  not  be  stored  a  second  time.  If  neither  append  nor 
delete  is  selected,  the  find  or  query  will  begin  a  new  internal  record  list  and  the  previous  contents  will 
be  lost. 

The  choices  entered  on  this  example  screen  will  result  in  all  the  records  within  a  1500  (meters)  radius 
of  the  target  point  (to  be  chosen  with  the  mouse)  being  selected  and  stored  on  the  internal  record  list  by 
find  or  query.  They  are  sorted  and  stored  in  order  of  proximity'  to  the  target.  If  a  specific  record  is 
used  as  the  target,  it’s  representative  point  (label  point)  is  the  target  coordinates,  and  it  is  always  placed 
first  in  the  retrieved  list.  If  a  mouse  is  chosen  to  select  the  target  point,  a  menu  to  display  reference 
maps  is  presented,  exactly  as  in  choice  (6),  prior  to  actually  activating  the  mouse. 
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QUERY/FIND:  REGION/MASK/TARGET  SELECTION  MENU 
Data  base  <arch>  (READONLY)  in  rnapset  PERMANENT?*  open.  25  records. 

Mark  requests  with  V  and  enter  required  values. 

Respect  current  region  x 

Respect  current  MASK  x 
(forces  current  region) 

A.  Hnd  all  sites  within  (or  outside)  a  circular  target  x 

and  give  the  radius  (negative  for  outside)  1500.00 _ 

OR 

B.  Find  a  number  of  sites  nearest  a  point  _ 

and  the  number  of  sites  requested  _ 

After  selecting  A  or  B,  complete  one(!)  of  these: 

1.  x  to  select  target  point  with  mouse  x 

2.  Enter  site  number  for  target  point  _ 

3.  Target  coordinates  east  0.00 _ 

north  0.00 _ 

Append(a)  or  Delete(d)  to  the  current  FINEMQUERY  list 
Reset  to  default  choices  for  this  menu  _ 

AFITR  COMPLETING  ALL  ANSWERS,  HIT  <ESC>TO  CONTINUE 
(OR  <Ctrl-C>TO  CANCEL) 

QUERY  COMMAND  MENU 

The  following  screen  completes  the  information  for  a  query  (choice  4).  It  may  be  left  Hank  if  n  • 
"where  clause"  is  required.  After  a  successful  query,  the  selected  records  are  displayed  one  at  a  time 
hy  hitting  ESC;  CI'RUC  will  quit  the  display  and  return  to  the  main  menu  where  several  choices  of 
operation  on  the  retrieved  sites  are  offered.  The  SQL  "sort  by”  clause  may  also  be  used  after  the  where 
clause  to  control  the  order  selected  records  are  presented;  however,  if  option  A  or  B  in  the  TARGET 
MENU  has  Ixten  selected  it  causes  sorting  by  proximity  to  the  target  location  which  will  override  the 
order  produced  by  tire  "sort  by"  clause. 
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QUERY  COMMAND  CONSTRUCTION  SCREEN 
Data  base  <vells>in  mapset  <grant>open.  25  records. 

The  SQL  select  query  will  use  the  current  region 

and  a  target  clause  of  ’distance  from  596463.15  4919041.88’ 

where  date  =  10/16/89  and  ppm_Cr  gt  10 _ 


(Enter  .show  on  a  line  to  review  screen  layout  and  field  names.) 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  <£SC>TO  CONTINUE 
(OR  <Qri-C>TO  CANCEL) 


MANAGEMENT  MENU 

Choice  13  from  the  main  menu  presents  this  menu.  Each  item  is  discussed  below. 

v.db.rim  DATA  BASE  MANAGEMENT  MENU 
Data  base  <fires>in  mapset  <Yellcrw>open.  250  records. 

1  Make  a  New  Data  Base  in  Current  Mapset 

2  List  Available  Data  Bases 

3  Remove  (PERMANENTLY)  Data  Base  from  Current  Mapset 

4  Recover  a  Data  Base  from  a  RIM  ASCII  File 

5  Show  Screen  Layout  of  Current  Data  Base 

6  Backup  (UNLOAD)  Data  Base  to  RIM  ASCII  Format  File 

7  Pack  die  Current  Data  Base 

8  Read  a  vector  map  into  the  Current  Data  Base 

9  Execute  a  Bourne  Shell  Command  Dne 

0  Return  to  Main  Menu 
0_  Your  selection 

AFTER  COMPLETING  ALL  ANSWERS,  HIT  ESC >  TO  CONTINUE 
(OR  <OrlO'IO  CANCEL) 

1.  Use  this  choice  to  create  a  new  data  base  in  the  current  GRASS  mapset.  See  section  below  on 
MAKE  A  NEW  DATA  BASE. 

2.  List  available  data  bases.  Like  option  2  on  Main  Menu. 

3.  Delete  an  entire  data  base  from  the  current  mapset.  The  name  of  the  data  base  and  additional 
confirmation  of  the  action  are  prompted  for.  Be  careful! 


GRASS  4.0  (Summer  1991) 


U.S.  Army  CTRL 


386 


v.db.rim 


GRASS  Reference  Manual 


v-dbrim 


4.  Choice  6  allows  backup  of  the  definition  and  data  parts  of  a  data  base  to  a  transportable  text  file. 
To  n>"  iild  (or  build  for  the  first  time)  a  v.db.rim  data  base  from  one  of  these  tact  files  do  the  following 
steps: 


#  see  if  the  rim  directory  exists. 

Is  $LOCA110N/rim/vect 

#if  the  directory  was  not  found,  make  it. 
mkdir  $LQCATIQN/rim 
mkdir  SLOCATION/rim/vect 

#  change  directory  to  it. 
cd  SI/XJATION/rimAect 

#have  rim  build  and  load  the  binary  data  base  files, 
rim 

RIM>  input  ’/path/to/fyourAextfile’ 

RlM>exit 

Ihe  data  base  is  thus  created  in  the  current  mapset.  Several  v.db.rim  commands  should  be  run  to 
verify  the  integrity  of  the  newly  created  data  base. 

5.  This  merely  shows  the  screen  layout  of  the  currently  open  data  base.  It  is  a  useful  way  to  quickly 
sec  the  layout  and  review  the  field  names  and  types. 

6.  When  backing  up  to  a  text  file,  the  RIM  UNLOAD  command  is  run  with  the  output  directed  to  a 
file  of  the  user’s  choice.  See  4  above.  It  is  wise  to  do  this  operation  after  extensive  changes  or 
additions  of  data  records.  The  resulting  text  file  can  be  written  to  tape  for  preservation,  or  shared  with 
other  GRASS  systems,  if  desired.  Data  bases  may  aiso  be  backed  up  by  copying  the  three  binary  files 
that  comprise  the  data  base  to  a  different  directory  with  the  UNIX  cp  command. 

7.  After  deleting  and  adding  a  large  number  of  site  records,  some  "wasted"  disk  space  will  be  present 
in  the  binary  data  base  files.  This  procedure  will  perfonn  an  unload  and  a  reload  automatically  to 
recover  this  unusable  disk  space.  If  there  is  any  problem  reopening  the  data  base  after  packing,  the 
user  is  notified  and  can  recover  in  various  ways  depending  cm  the  backups  which  have  been  done. 

<S.  Data  (records)  may  be  loaded  into  a  data  base  from  an  existing  GRASS  vector  map.  This  procedure 
will  prompt  for  the  vector  map  name  and  then  add  a  record  to  the  currently  open  data  base  for  each 
labeled(!)  line  in  the  vector  field.  The  user  may  also  enter  the  name  of  an  integer  field  in  which  to 
store  the  label  (from  the  dig_att  file)  for  each  vector,  and  a  text  field  in  which  to  store  the  descriptive 
text  from  the  dig_cats  file  for  each  vector.  The  record  number,  vector  ty  pe,  map  number  and  location 
coordinate  fields  (s,v,m,x  and  y  types)  are  automatically  loaded  for  each  site  record  by  this  procedure; 
other  fields  nitty  lie  later  edited  with  the  "change”  function. 

9.  Ihis  choice  is  the  same  as  choice  14  on  the  main  menu. 

MAKE  A  NEW  DATA  BASE 

After  entering  the  name  of  the  new  data  liase  you  wish  to  create  (7  characters  maximum),  you  then 
decide  how  to  input  the  information  required.  I"his  input  may  lie  from  a  text  file,  or  may  be  entered 
directly  using  the  editor  of  your  choice:  the  former  is  recommended.  .See  discussion  in  .make  in  section 
one. 
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NOTES 

This  program  is  included  in  the  GRASS  4.0  release,  but  is  not  automatically  compiled  with  other 
GRASS  commands.  The  user  must  compile  this  program  separately. 

v.db.rim  interfaces  to  the  RIM  program.  Both  rim  and  v.db.rim  contain  FORTRAN  code.  The  user 
must  have  access  to  a  FORTRAN  compiler  in  order  to  compile  and  use  v.db.rim.  See  the  HITS 
section,  below,  for  location  of  source  code  for  RIM  and  b.rim. 

A  "date"  type  field  should  be  added  to  future  versions.  This  version  only  allows  storing  of  dates  as 
strings  (unless  the  user  codes  them  to  integers),  and  thus  only  string  type  searches  can  lx;  made  for 
dates. 

FILES 

Source  code  for  RIM  is  located  under  SGISBASE/.  ./sir  .reiatal/ri  m 

Source  code  for  v.db.rim  is  located  under  SGISBASI7../src.g;irden/grass.rimA  .db.rim 

SEE  ALSO 

RIM  User’s  Manual,  by  James  Fox,  Academic  Computing  Services,  Univ.  of  Washington.  See 
especially  Appendix  B  on  redistribution  of  RIM. 

GRASS  4.0  Installation  Guide,  by  James  Westervelt  and  Michael  Shapiro,  U.S.  Army  Construction 
Engineering  Research  laboratory 

Gen.Maps,  GenJractmap,  g.mapsets,  rrutiger .region,  s.db.rim,  smenu,  v.in.tiger 
AUTHORS 

James  Jinthome  and  David  Satnik,  GIS  Laboratory,  Central  Washington  University,  Ellensburg,  WA 
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NAME 

v.digit  -  A  menu-driven,  highly  interactive  map  development  program  used  for  vector  digitizing, 
editing,  labeling  and  converting  vector  data  to  raster  format. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.digit 

DESCRIPTION 

Ihe  GRASS  pregram  v.digit  is  a  menu-driven,  highly  interactive  map  development  program  used  for 
inputting  analog  map  data  into  a  GRASS  vector  format,  v.digit  contains  programs  for  vector  digitizing, 
editing,  labeling,  windowing,  and  converting  vector  data  to  GRASS  raster  format. 

v.digit  consists  of  two  parts:  an  initialization  procedure,  and  a  multiple  menu-driven  environment. 

1)  The  initialization  procedure  involves  choosing  a  digitizer,  choosing  die  name  of  a  vector  map  layer 
to  digitize,  and,  if  needed,  registering  a  map  to  the  digitizing  surface. 

2)  Ihe  second  part  of  v.digit  is  a  multiple-menu  environment  in  which  digitizing,  editing,  labeling,  and 
other  options  are  available.  It  is  within  this  second  portion  of  v.digit  that  all  vector  creation  occurs. 

NOTES 

v.digit  was  written  to  optimize  digitizing  speed  and  performance.  It  has  a  convenient  graphic  display 
format  and  very  convenient  windowing  capabilities.  Features  are  color-coded  for  ease  of  identification 
and  verification.  Different  color  schemes  may  be  user-chosen  to  customize  a  digitizing  session. 

Area,  line,  and  point  features  may  be  digitized  in  both  "stream"  and  "point"  modes.  Both  a  mouse  and 
a  digitizer  may  be  used  to  perform  windowing  functions.  labeling  and  editing  are  done  from  within 
v.digit,  rather  than  through  a  separate  set  of  programs. 

v.digit  has  capabilities  that  allow  users  to  convert  vector  map  layers  to  GRASS  raster  format,  to 
overlay  already  existing  vector  map  layers  onto  the  feature  being  digitized,  and  set  a  multitude  of 
parameters  to  customize  a  digitizing  session. 

v.digit  may  be  used  with  or  without  a  digitizer.  Many  options  are  available  if  no  digitizer  is  used. 

All  options  available  within  v.digit  are  contained  within  10  menus.  Movement  from  menu  to  menu  is 
done  by  c hosing  the  movement  options  specified  at  the  bottom  of  each  menu. 

SEE  ALSO 

GRASS  Tutorial  -  digit:  Its  Use  and  Its  Features 

v.i Import,  v.in.ascii,  v.oui. ascii,  v.out.rast,  v support 

AUTHORS 

Duvid  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Michael  Higgins,  U.S.  Anny  Constniction  Engineering  Research  laboratory 
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NAME 

v import  -  Converts  ASCII  Digital  Line  Graph  (DLG)  files,  binary  DLG  files,  and  ASCII  vector  files 
into  binary  vector  files  and  creates  the  needed  vector  support  files. 

(GRASS  Vector  Program) 

SYNOPSIS 

vJmport 

DESCRIPTION 

v.import  is  an  interactive  program  which  runs  other  vector  import  programs.  It  allows  you  to  import 
DLG  or  ASCII  vector  files  into  GRASS  vector  format.  It  also  runs  v support.  No  arguments  are 
required  on  the  command  line. 

This  program  performs  all  of  the  processes  that  are  needed  to  convert  ASCII  Digital  line  Graph  (DLG) 
files,  binary  DLG  files,  and  ASCII  vector  files  into  binary  vector  files.  It  also  creates  two  support  files, 
the  dig_plus  file  and  the  dig_att  file  (only  created  when  importing  DIG  files).  Ihe  dig  pi u s  file 
contains  topological  information  obtained  by  analyzing  the  vector  file.  Ihe  dig  alt  file  contaias 
category  (attribute)  information  files  by  the  labeling  function  of  the  GRASS  v.digit  program.  All  of  the 
above  files  must  be  run  through  v.import  before  they  can  be  ased  in  the  v.digit  program  of  GRASS 
4.0. 

IMPORT  FILES 

After  entering  the  command  ▼impart,  the  user  will  be  asked  for  the  type  of  file  that  is  to  be  imported 
and  for  which  support  files  will  be  created: 

Import  to  GRASS  Vector  Format  and  Create  Needed  Support  Files 

1  -  ASCII  DIG  file  to  GRASS  Vector  Format 

2  -  Binary  DIG  file  to  GRASS  Vector  Format 

3  -  ASCII  VECTOR  file  to  GRASS  Vector  Format 

4  -  Binary  VECTOR  file  to  GRASS  Vector  Format 

If  numbers  1-3  are  chosen,  v.import  will  respond  with  the  current  data  base  units  (in  feet  or  meters), 
and  ask  if  the  new  vector  file  is  in  the  correct  units  for  the  data  base  location.  If  the  new  vector  file  is 
not  in  the  correct  units,  v.import  will  not  allow’  it  to  be  placed  in  the  current  data  hasc  location.  For 
each  data  base  location,  all  map  layers  should  have  the  same  units.  If,  for  some  reason,  a  map  layer 
uses  different  units  than  the  rest  of  the  map  layers  in  the  same  ilata  base  location,  a  new  data  base 
location  will  have  to  be  created  for  it. 

ASCII  DLG  Kile  to  GRASS  Vector  Format: 

Converts  an  ASCII  DIG  file  (such  as  those  created  in  GRASS  2.0)  to  a  GRASS  vector  file  and  creates 
the  dig.  plus  and  dig_att  support  files.  The  user  is  asked  two  questions: 

1.  Determine  if  this  map  is  composed  of  Area  or  line  information. 

Do  you  want  to  give  precedence  to  Areas  (opposed  to  lines)?  (y/n)  [yj 

NOTE:  Some  machine-processed  DIG  files  do  not  make  tlie  distinction  between  lines  and 
;irea  edges.  For  example,  in  a  roads  map,  where  the  desired  information  is  line  data,  a 
downtown  block  surrounded  by  roads  may  be  processed  as  ;m  area.  Because  of  this,  the  user  is 
asked  to  choose  whether  to  give  precedence  to  areas  or  lines.  If  precedence  is  given  to  lines, 
the  user  should  be  aware  that  any  lines  that  bound  unlalxded  areas  in  tlie  DI  G  file  will  Ire 
stored  as  line  data.  Any  unlabelcd  areas  would  therefore  lie  lost  (this  is  onlv  a  concern  when 
areas  arc  unlabelcd,  labeled  area  information  will  lie  retained).  If  precedence  is  given  to  ;ireas, 
lines  will  lie  stored  as  boundaries  to  areas  that  are  unlabelcd. 
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2.  During  the  building  of  the  Vector  format: 

Do  you  want  to  snap  nodes  to  other  nodes  within  a  threshold  (yAi)  [n] 

NOTH:  HI-  CAR1TUL!  This  threshold  is  calculated  using  the  scale  of  the  original  DLG  or 
dig  file.  If  the  threshold  is  too  high,  excessive  snapping  may  occur,  destroying  the  file.  In 
general,  users  seldom  need  to  snap  nixies.  If  snapping  of  nodes  is  desired,  the  user  may  want 
to  nin  v. support  separately,  v support  allows  the  user  to  set  the  snapping  threshold. 

lhis  process  is  done  in  three  phases: 

1.  Ihe  ASCII  DIG  file  is  converted  to  a  binary  DLG  file. 

2.  Ihe  binary  DLG  file  is  converted  to  a  binary  Vector  file,  and  the  dig  att  support  file  containing 
attribute  (category)  information  is  created. 

3.  Ihe  dig_plus  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 


Binary  DLG  Kile  to  GRASS  Vector  Format: 

C  onverts  binary  DIG  files  (such  as  those  created  in  GRASS  2.0)  to  a  vector  file  and  creates  the 
dig_plus  and  dig  att  sup[xirt  files.  The  user  is  asked  whether  precedence  should  be  given  to  Areas  or 
lines  ;uid  if  nixies  shixild  lx-  snapped  to  other  nodes  within  a  calculated  threshold. 

lhis  process  is  done  in  two  phases: 

1 .  The  binary  dig  file  is  converted  to  a  binary  vector  file,  and  the  dig  att  vector  support  file  containing 
attribute  information  is  created. 

2.  Ihe  dig  plus  vector  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 

ASCII  Vector  file  to  GRASS  Vector  Format: 

Converts  ASCII  vector  files  (such  as  those  created  in  GRASS  2.0)  into  GRASS  binary  vector  files,  and 
creates  the  dig_  plus  vector  support  file.  Since  a  vector  maintains  the  distinction  between  lines  and 
area  edges,  the  user  is  not  asked  to  give  precedence  to  either.  However,  the  user  will  be  asked  if 
snapping  from  nixies  to  other  nodes  within  a  calculated  threshold  is  desired. 

lhis  process  is  done  in  two  phases: 

1.  Ihe  ASCII  vector  file  is  converted  to  a  binary  vector  file,  aixl  the  dig  plus  vector  support  tile  is 
created. 

2.  Ihe  digplus  vector  supjxMl  file  is  created  by  analyzing  the  vector  file  for  topological  information. 


Binary  Vector  file  to  GRASS  Vector  Format: 

Creates  the  dig  plus  vector  support  file. 


lhis  prixess  is  done  in  one  phase: 

I .  Ihe  dig  plus  v  ector  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 
SHE  ALSO 

v. digit,  v.in.ascii,  v. support 
AUTHORS 

Michael  Higgins.  IJ.S.  Anny  Constnution  Ingi  nee  ring  Rese;irch  laboratory 
Dhvid  ( ierdes.  US.  Army  Constnution  lug  i  nee  ring  Research  lalxxatory 
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NAME 

v.in.arc  -  Converts  data  in  ARC71NF0  format  to  GRASS’S  vector  format,  and  stores  output  in  the 
user’s  current  GRASS  mapset. 

(GRASS  Vector  Data  Import  Program) 

SYNOPSIS 

v.in.arc 
v.in.arc  help 

van^irc  [-n]  type  -name  lines  in  =name  [points_in ^narne]  [text_in=/M/ne] 
vector^out  =name  [idcol  =value]  [cat col  -value]  [attcol  =value\ 

DESCRIPTION 

'Die  user  may  wish  to  use  GRASS  programs  on  data  files  that  were  created  by  other  GISs.  To  do  tliis, 
the  user  must  first  convert  data  files  in  these  systems’  formats  to  GRASS’S  file  format.  Bringing  data 
from  other  systems  into  GRASS  is  termed  file  import.  Sending  GRASS  data  files  out  into  other 
systems’  fonnats  is  tenned  file  export. 

A  variety  of  GRASS  prog  nuns  exist  to  import  and  export  data  to  and  from  GRASS.  The  v.in.arc 
program  will  convert  vector  data  in  ARC/INFO' s  "Generate"  format  to  GRASS’s  vector  file  formal,  and 
bring  it  into  the  user’s  current  GRASS  mapset.  The  files  to  be  imported  to  GRASS  must  first  have 
been  exported  from  ARC/INPO  using  the  ARC/INFO  Ungenerate  command,  and  may  represent  either 
linear  features  ("line  coverage")  or  areal  features  ("polygon  coverage”).  Ihe  ARC/INFO  User’s  Guide 
describes  how  files  containing  linear  and  polygonal  features  can  be  exported  from  ARC/INH),  in  a 
section  detailing  the  use  of  the  Ungenerate  command. 

Qtce  converted  with  the  ARC/INK)  Ungenerate  command,  the  files  to  be  imported  into  GRASS  must 
be  placed  in  a  directory  named  arc  in  the  user  s  current  mapset.  If  the  arc.  directory  does  not  exist,  it 
must  be  created  (e.g.,  with  the  command  mkdir  $IOCATION/arc)  before  copying  the  ARC- INK)  files 
to  be  converted  into  it. 

(i v.in.arc  can  be  used  to  convert  ARC- INFO  data  from  other  mapsets  as  well,  since  the  program 
searches  for  the  specified  input  file  names  in  the  arc  directories,  if  any  exist,  in  the  mapsets  in  the 
user’s  current  mapset  search  path.) 


OPTIONS 

Program  parameters  and  the  flag  have  the  following  meanings. 

Flag: 


-n 


Parameters: 


Ncatline.  Vectors  representing  a  box  (neatline)  around  the  input  vector  data  will 
be  inserted  into  the  output  GRASS  vector  file. 


typ rename 

lines_in=name 

point  sin  =name 

text.An=name 

vector  out  =name 
idcol  =value 


Coverage  type.  Either  polygon,  or  line. 

Options:  polygon,  line 

ARC/INFO  ungenerate  lines  file;  ungeneratc  fonnat  input  file  containing  line  or 
polygon  coordinates. 

ARCTINK)  ungenerate  label  points  file;  ungeneratc  format  input  file  containin' 
lalxd- point  coordinates;  only  applies  to  ’polygon’  type  data. 

ARCTINK)  ungeneratc  label-text  file;  ungeneratc  fonnat  input  file  containing 
category  numbers  and  (optionally)  attribute  text. 

Resultant  GRASS  vector  output  file. 

ID  Number  column  in  label-text  file.  Number  of  label-text  column  containing 
line-II)  numbers. 
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catroi  value  GRASS  category  column  in  label-text  file.  Number  of  label-text  column 

containing  category  values. 

attcol  =value  GRASS  attribute  column  in  label-text  file.  Number  of  label-text  column 

containing  attribute  text. 

This  program  can  be  run  either  non-interactively  or  interactively.  The  prcgram  will  run  non- 
intcractively  if  the  user  specifies  the  (optional)  flag  setting  and  needed  parameter  values  on  the 
command  line,  using  the  form: 

v.in.arc  [hd]  ty  pt^name  lines. in  =name  [points_in=mi/n(]  [ text  in  =name] 
vector  (Hit  name  [ideal  =value]  [catcol  ^-value]  [attcol  =value\ 

Alternately,  the  user  c;ui  type: 

v.in.arc 

on  the  command  line  without  program  arguments;  in  this  case,  the  program  will  prompt  the  user  foi 
the  flag  setting  and  parameter  values  in  the  manner  shown  below. 

In  ARC/1NFO,  three  files  are  used  to  store  jxJygon  data: 

1)  a  lines  file,  which  contains  coordinates  of  all  the  area  edge  lines; 

2)  a  label-point  file,  which  contains  coordinates  of  label-points  (each  of  which  has  associated  with  it  a 
unique  label-point  ID  number).  One  label-point  is  associated  with  each  polygon  defined  in  the  lines 
file, 

3)  a  label -text  fide,  which  associates  each  label-point  ID  number  with  a  category  number  and  category 
("attribute")  text. 

linear  feature  data  are  stored  in  two  files: 

1)  a  lines  file,  which  contains  geographic  coordinates  defining  lines,  each  with  a  line-ID number;  and 

2)  a  label-text  file,  which  associates  each  line-ID  number  with  a  category  number  and  attribute  text. 

Ihcse  data  files  arc  described  in  further  detail  below,  under  the  DATA  FILE  FORMATS  section. 
INTERACTIVE  MODE 

Ihe  program  will  prompt  the  user  for  the  flag  setting  and  parameter  values  if  the  user  does  not  specify 
these  on  the  command  line.  First,  the  user  will  be  asked  to  assign  a  name  to  the  vector  file  to  store 
program  rxitput: 

VECTOR  (DIGH)  FILENAME 
Enter  ’list’  for  a  list  of  existing  binary  vector  files 
I  fit  RITURN  to  c;ukc1  request 

> 

Next,  the  user  is  asked  to  specify  the  COVERAGE  (feature)  type  to  be  imported  into  GRASS.  Valid 
coverage  types  are  polygon  and  line. 

COVERAGE.  TYPE 
Enter  "polygon"  or  "line" 

I  fit  RETURN  to  c;uicel  request 

> 


IMPORTING  A  POLYt  iON  COVERAGE 

If  the  user  chooses  POLYfXJN  coverage,  he  is  asked  if  he  wishes  a  ncatline  placed  arouixl  his  data, 
fl be  existence  of  ncallines  in  the  output  file  can  facilitate  subsequent  patching  of  data  files.) 


(iRASS  4.0  (Summer  l‘«)|) 


IJ.S  Anm  CE.RI 


393 


v.in.arc 


GRASS  Reference  Manual 


v  jn.arc 


NEATUNE 

Do  you  want  a  neatline  ? 

Enter  "yes"  or  "no" 

> 

If  the  user  types  yes.  vectors  that  box  the  data  will  lx:  inserted  into  the  GRASS  vector  (xitput  file 
(vector  _out) ;  otherwise,  no  neatline  will  lie  inserted  into  the  output  file. 

Next,  the  user  is  prompted  for  the  name  of  an  existing  lines  file  containing  the  geographic  coordinates 
of  the  arcs  forming  polygon  fieri  meters,  lhe  lines-file  is  created  with  the  ARCTINFO  Ungenerate 
UNI'S  option,  and  is  in  the  same  format  at  the  prefbc.pol  file  t  reated  by  the  v. out. arc  program,  lhe 
user  sees  the  following  prompt: 

LINES  FILENAME 

Enter  name  of  the  file  created  with  the  LINES 
option  of  the  ARC  /INK)  Ungenerate  command, 
lit  RETURN  to  cancel  request 
> 

The  next  prompt  for  coverage  type  "polygon”  asks  for  the  name  of  an  existing  label-points  file.  The 
label-points  file  is  created  with  the  Ungenerate  POIN’IS  option,  and  is  in  the  same  format  as  the 
prefix.lab  file  created  by  the  v.out.arc  program,  lhe  user  sees  the  following  prompt: 

LABH  .POINTS  FILENAME 
Enter  name  of  file  created  with  the  I’OINI'S 
option  of  the  ARC/1  NEO  Ungenerate  command, 
lit  RETURN  if  there  is  no  such  file 
> 

finally,  the  program  asks  the  user  for  the  name  of  an  existing  label-text  file.  This  lile  associates  each 
label-point  ID  number  with  a  text  string.  It  is  in  the  same  fonnat  as  the  prefix.txt  file  created  by  the 
v.out.arc  program. 

LABELTEXT  FILENAME 
Enter  the  name  of  a  file  that  associates 
label-point  ID  numbers  with  text  label  strings 
Hit  RETURN  if  there  is  no  such  file 
> 

v.in  arc  then  scans  the  label-text  file  to  find  the  numbers  of  lines  and  columns,  the  column  headers  (if 
any,;,  and  the  first  three  lines  of  actual  data  in  the  file.  It  displays  this  information  to  standard  output  to 
help  the  user  determine  which  columns  will  hold  the  ID,  Category'  value,  and  Attribute  text  data  in  the 
new  vector  < xitput  file.  A  sample  of  the  program’s  output  is  shown  below: 

lhe  LABELTEXr  file  has  been  scanned.  There  arc  132 
lines  in  the  file  and  <S  columns  in  the  file 

Column  headers  of  the  LABEL'IEXT  file: 

rec#  ARIA  PERIMETER  SOILS#  SOUS  ID  SOIL  CODE  DRAINXT7DE  1XTUR  CODE 
Here  are  the  first  three  lines: 

1  -2.30228E+O7  19.399.848  1  0  0  0  0 

2  81,079.875  1,678.826  2  1  15  3  3 

3  955,952.500  10229.637  3  2  19  8  8 
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The  column  of  category  values  must  contain  only  integer  values.  Hie  attribute  text  column  can  contain 
a  floating  point  number,  an  integer,  or  a  word  (text  string). 

finally,  the  user  is  prompted  to  enter  line  ED,  category  value,  and  attribute  text  column  numbers. 


Enter  the  number  of  the  column  that  should  be  used 
for  line  EDS  (probably  the  column  with  -ID)  : 

Enter  the  number  of  the  column  that  is  to  be  used 
for  GRASS  category  values: 


Inter  the  niunber  of  the  column  that  should  be  used 
for  GRASS  attribute  text: 

Qice  these  column  numbers  have  been  entered,  vJnutrc  will  begin  converting  the  ARC/INK) 
"Generate"  format  files  into  GRASS  vector  file  format. 


IMI*ORTING  A  LINE  COVERAGE 

Ihe  user  will  also  lie  prompted  for  input  when  importing  ARC7INK)  files  containing  linear  features 
("line  coverage")  data.  like  polygon  data,  linear  feature"  are  constructed  by  the  series  of  arcs  (aka, 
vectors)  defining  their  perimeters.  If  the  user  selects  LINE  coverage,  the  prompts  seen  by  the  user  will 
be  different  in  two  respects  from  those  for  POLYGON  coverage.  First,  the  user  will  not  be  asked 
whether  or  not  a  neatline  is  desired;  and  second,  no  label-points  file  name  will  lie  requested.  In  other 
res|iects,  the  treatment  of  LINE  coverage  is  identical  to  that  for  POLYGON  coverage. 

Ihe  user  is  prompted  for  the  name  of  the  lines-file  containing  the  geographic  coordinates  of  these  arcs. 
The  lines-file  must  first  have  been  created  with  the  ARC/INFO  Ungenerate  UNFS  option,  and  is  in 
the  s;uue  fonnat  as  the  prefix.lin  file  created  by  the  GRASS  v.out.orc  program. 


DATA  FII.K  FORMATS 

Following  are  examples  of  the  data  files  discussed  above. 


LINES  FILE,  also  known  as  prefixJin  or  prefix.pol  file. 

This  type  of  file  am  be  created  in  ARC/INFO  by  using  tlie  lines  subcommand  of  the  Ungenerate 
command.  Each  line  (aka,  arc)  is  defined  by  a  line-ED  number,  followed  by  a  list  of  at  least  two 
easting  and  northing  axxdinatc  pairs,  followed  by  a  line  with  the  word  "END’.  The  file  is  tenninated 
with  the  word  "END*. 


The  line-ID  numlier  is  important  only  Ur  line  coverage  data.  Eor  a  line  coverage,  the  line- ID  number 
is  the  numlier  that  associates  each  line  with  its  attribute  data. 


3 

71  m6.(J000(X> 
7 11 35!. 875000 

INI) 

3 

700562-500000 
709617.250000 
70%  17.250000 
709585.000000 


4651803.000000 

4651786.000000 


4651731.000000 

4651624.000000 

4651567.000000 

4651503.000000 
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709601.125000 

709696.875000 
709720300000 
709823.750000 

709893.125000 
END 

3 

710296.875000 

710295.125000 
710223.000000 
71015 1.500000 
END 

END 


4651470.000000 

4651503.000000 

4651574.000000 

4651575.000000 

4651741.000000 


4651491.000000 

4651470.000000 

4651454.000000 

4651463.000000 


LAI  SUBPOINTS  RED  also  known  as  prefixJab  file. 

This  type  of  file  can  be  created  in  ARC/INFO  using  the  Points 
option  of  the  Ungenerate  command. 

The  first  number  on  each  line  is  a  label-point  ID  number.  ;uid  the 
following  two  numbers  are  (respectively)  the  easting  and  northing 
coordinate  pair  representing  the  geographic  location  of  the  label- point. 


1 

711539.875000 

4651743.000000 

-1 

711429.000000 

4650632.000000 

3 

711027.625000 

4651736.000000 

4 

711022.625000 

4651519.000000 

5 

710482.750000 

4651494.000000 

6 

710474500000 

4651667.000000 

7 

709269.750000 

4651018.000000 

8 

709726500000 

4651604.000000 

9 

708926375000 

4651195.000000 

10 

708567500000 

4651644.000000 

11 

END 

708272.750000 

4651407 .000000 

LABIiDTEXT  FILE  also  known  as  prefix.t  tf  file. 

The  ARC/INFO  Display  command  can  be  used  to  create  this  type  of  file. 


1 

-230228E+07 

19399.848 

1 

0 

0 

0 

2 

81,079.875 

1,678.826 

2 

1 

15 

3 

3 

955,952500 

10229.637 

3 

2 

19 

8 

4 

41,530.875 

926.887 

4 

3 

17 

3 

5 

87,900.188 

1,900.909 

5 

4 

1? 

3 

6 

166,125.125 

3312.950 

6 

5 

1'. 

3 

7 

29,460563 

824.968 

7 

6 

17 

3 

8 

1022769.875 

9,105.707 

8 

7 

20 

9 

9 

51385.500 

1,075.638 

9 

8 

17 

3 

10 

376,834.875 

4,470.027 

10 

9 

9 

11 

65,802.688 

1375.088 

11 

10 

16 

3 

NOTES 

ARG/INFO  data  can  lie  imported  even  if  a  label-points  and/or  a  label-text  file  arc  missing;  however, 
the  lines  and/or  areas  imported  will  not  lie  labeled. 

v.in.arc  can  handle  label-text  files  both  with  and  without  header  lines. 
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This  program  remains  under  alpha  testily.  It  resides  in  the  src. alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

v.out.arc,  v.support 

AUTHOR 

David  Johnson 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

v.in.ascii  -  Converts  ASCII  vector  map  layers  into  binary  vector  map  layers. 

(GRASS  Vector  Data  Import  Program) 

SYNOPSIS 

v.in-ascii 
vjnjucii  help 

vJn^scii  input  name  output  -name 
DESCRIPTION 

vjn.ascii  converts  a  vector  map  in  ASCII  format  to  a  vector  map  in  binary  format.  The  user  can  run 
this  program  non-interactively  by  specifying  all  frog  ram  options  on  the  command  line,  in  the  form: 

vJnaiscii  input  =name  output  =name 

Parameters: 

input  =name  Name  of  an  ASCII  vector  file  to  be  converted  to  binary  vector  file. 

output  =name  Name  given  to  binary  vector  output  file. 

If  the  user  runs  v.in.ascii  without  giving  program  arguments  on  the  command  line,  the  program  will 
prompt  the  user  for  input  and  output  file  names. 

NOTES 

After  running  this  program,  GRASS  support  files  must  be  built  for  the  binary  output  file  before  the  user 
can  use  the  file  in  v. digit.  The  user  can  run  v support  to  create  GRASS  support  files  for  the  output 
file. 

The  GRASS  program  v. out. ascii  performs  the  function  of  v.in.ascii  in  reverse;  i.e.,  it  converts  vector 
files  in  binary  format  to  ASCII  format.  These  two  companion  programs  are  useful  both  for  importing 
and  exporting  vector  files  between  GRASS  and  other  software,  and  for  transferring  data  between 
machines. 

The  output  from  vJn.ascii  will  be  placed  into  $LOCATION/dig. 

SEE  ALSO 

v.digit ,  v.import,  v. out. ascii,  v.support 
AUTHORS 

Michael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v.in.dlg  -  Converts  an  ASCII  or  binary  USGS  DLG-3  (bdlg)  file  to  a  binary  GRASS  vector  (<fig)  file. 
(GRASS  Vector  Data  Import  Program) 

SYNOPSIS 

van  .dig 
v.in.dlg  help 

vJn.dlg  [-M]  input  =name  output  =name 
DESCRIPTION 

Ibis  program  converts  an  ASCII  or  binary  USGS  DLG-3  (dig  or  bdlg)  file  into  a  binary  GRASS  vector 
(dig)  file. 

v.in.dlg  also  creates  a  dig_att  file  containing  the  label  information  ’stripped’  from  the  DLG-3  file. 
1  low  ever,  the  user  must  run  v. support  (or  v. import  option  4)  on  the  output  file  created  by  v.inuUg  to 
create  a  digjplus  file  containing  the  file  topology,  before  using  the  output  file  in  v. digit. 

The  user  can  avoid  this  two-step  process  by  converting  the  ASCII  or  binary  DLG-3  file  in  binary 
GRASS  vector  format  using  option  1  or  2  of  the  GRASS  program  v import. 


Flags: 

-b  Input  is  a  binary  DLG-3  file  (default  is  ASCII). 

H  Gve  precedence  to  line  information  (default  is  area). 


Parameters: 

input  name  Name  of  USGS  DLG-3  Optional  format  input  file. 

output  name  Name  to  be  assigned  to  the  binary  GRASS  vector  files  created. 

If  the  user  simply  types  v.inallg  without  specifying  parameter  values  on  the  command  line,  the 
program  will  prompt  the  user  to  enter  these. 

NOTES 

Area  vs  Line  Precedence: 

Some  machine- processed  DIG-3  files  do  not  make  the  distinction  between  line  ec^es  and  area  edges. 
For  example,  in  a  roads  map,  where  the  desired  information  is  line  edge  data,  a  downtown  block 
surrounded  by  roads  may  be  processed  as  an  area.  Because  of  this,  the  user  is  asked  to  choose  whether 
to  give  precedence  to  areas  or  lines.  If  precedence  is  given  to  lines,  the  user  should  be  aware  that  any 
lines  that  bound  unlabeled  areas  in  the  DIG3  file  will  be  stored  as  line  data.  Any  unlabeled  areas 
wtHild  therefore  be  lost  (this  is  only  a  concern  when  areas  are  unlabeled;  labeled  area  information  will 
be  retained).  If  precedence  is  given  to  areas,  lines  will  be  stored  as  boundaries  to  areas  that  are 
unlabeled. 


Building  support  files  with  v support : 

When  you  nui  v. support  you  will  liave  tlie  option  of  snapping  the  nodes  in  your  vector  file  that  fall 
within  a  certain  threshold  of  one  another.  WARNING:  the  default  threshold  is  calculated  using  the 
scale  of  the  original  DLG-3  file.  If  the  threshold  is  too  high,  excessive  snapping  may  occur,  destroying 
the  file!!  With  v. support,  the  user  has  the  option  of  snapping  or  not  snappire;  nodes,  and  further,  of 
setting  a  particular  snapping  threshold. 

SEE  ALSO 

v.digit,  v.import,  v. support 


3'H) 


GRASS  4.0  (Summer  1WI) 


L.S.  Anuv  (TRI, 


v.in.dlg 


GRASS  Reference  Manual 


v.in.dlg 


AUTHORS 

Michael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
David  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v.in.dxf  -  0 inverts  files  in  DXF  fonnat  to  ASCII  or  binary  GRASS  vector  file  format. 

(GRASS  Vector  Data  Import  Program) 

SYNOPSIS 

van.dxf 
v.in.dxf  help 

v.in.dxf  [-a]  dxf  =name  [lines=/iame[/uv7K,...]]  (labels  =name[/iame,...]]  [prefix  =/iame] 
DESCRIPTION 

Ihe  v.in.dxf  data  conversion  program  generates  GRASS  dig ,  dig_ascii,  and  dig_att  files  from  a  file  in 
DXF  format.  I  nch  layer  in  the  DXF  input  file  is  converted  to  a  separate  dig  (or  dig_ascii)  layer.  For 
each  DXF  layer  containing  text,  a  dig_att  file  is  also  created.  These  output  files  are  placed  in  the  dig, 
tiig_ascii,  and  dig_att  directories  under  the  user’s  current  GRASS  mapset. 

Output  front  tltis  program  is  designed  to  be  used  as  input  to  the  program  v.cadlabel. 

Ihe  v.i n.dxf  program  will  only  recognize  points,  lines,  polylines,  and  text  in  the  DXF  format,  and  will 
translate  these  to  GRASS  vector  format;  other  types  of  data  are  ignored. 


Flag: 

-a  Output  an  ASCII  GRASS  vector  ( dig_ascii )  file  rather  than  a  binary  GRASS  vector 

(dig)  file. 

Parameters: 

dxf  =name  Name  of  the  DXF  input  design  file  to  be  converted  to  GRASS  vector  format. 

lines  name\,name,...\  or  lines=in_name:out_/iame\,in_name:out_name,...\ 

Name(s)  of  layerfs)  in  the  DXF  input  file  containing  line  data,  and  (optionally)  the 
name(s)  to  be  assigned  to  the  GRASS  vector  data  ( dig  or  dig_ascii)  files  output. 

I X- fault :  Convert  each  layer  containing  data  in  the  Idxf  file  to  a  GRASS  vector  data 
(dig  or  dig  ascii)  file. 

\»b*\s~name\,name,...\  or  labels=isi ^iame:out _jiame\,in  name:oui_name,...\ 

Name(s)  of  layeifs)  in  the  DXF  input  file  containing  text  labels,  and  (optionally)  the 
n;une(s)  to  lx'  assigned  to  the  GRASS  vector  attribute  (dig_att)  files  output. 

Default:  Convert  each  layer  containing  text  labels  in  the  dxf  map  to  a  GRASS  vector 
altrilxite  (dig_alt)  file. 

Prefix  assigned  to  the  dig  or  dig_ascii  ;tnd  dig__att  output  file  names. 

Ihe  names  of  the  GRASS  vector  (dig,  dig_ascii,  and  dig_att )  files  output  are 
constructed  as  prefix. extension,  where  prefix  is  the  prefix  name  specified  by  the  user 
;uiil  extension  is  the  number  of  the  DXF  layer  from  which  the  data  were  obtained.  If 
the  user  does  not  specify  a  prefix  name,  the  output  files  take  their  prefix  from  the 
prefix  of  the  input  DXF  map  layer.  For  example,  for  the  DXF  file  named 
streams. dxf  containing  line  data  on  layer  15,  the  GRASS  vector  in.p  layer  output 
would  lx-  named  streams.15. 

Outputs  line  data  in  DXF  layer  15. 

Outputs  line  data  in  DXF  layers  15  and  16. 

lines  =ROADS,  WATER 

(Converts  line  data  in  DXF  layers  ROADS  and  WAFFR. 

Iines=15: 16  CXitputs  line  data  in  DXF'  layer  15,  aixl  places  it  in  the  dig  (or  dig_ascii)  file 

for  DXF  layer  16. 


prefix  -name 


EXAMPLES 

lines  =15 

lines  =15,16 
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the  examples  below  are  given  for  a  DXF  design  file  named  cont.dxf  containing  contour  lines  and 
contour  line  labels,  in  which: 

index  contour  lines  are  in  DXF  layer  9, 

intermediate  contour  lines  are  in  DXF  layer  11,  and 

index  labels  and  some  intermediate  contour  lines  are  in  DXF  layer  12. 

v.in.dxf  can  be  run  with  default  values,  as  shown  below: 

v Jn.dxf  dxf  =co*it.dxf 

Here,  this  is  equivalent  to  running  the  following  command: 

v Jn.dxf  dxf=cont.dxf  lines=9,ll,12  labels =12 

Ether  of  the  above  commands  will  produce  three  GRASS  dig  files  (named  coru.9,  cont.ll,  and 
cont.12)  and  one  digjatt  file  (named  cont.ll). 

hi  our  example,  however,  the  cont.12  file  contains  intermediate  contour  lines  that  the  user  would  like 
to  add  to  the  dig  file  cont.ll.  Our  user  also  wishes  to  use  a  different  file  prefix  than  the  default  prefix 
cont.  The  user  therefore  types  the  following  command: 

vin.dxf  dxf  =c  out  .dxf  lin«s=9, 11, 12:11  labels =12  prefix  =contour 

The  above  command  will  generate  three  dig  files  (named  contour.9,  contour.il,  contour. 12),  and  will 
create  one  digjatt  file  containing  text  labels  (called  contour. 12).  No  contour  lines  will  appear  in  the 
dig_att  file. 

NOTES 

Output  Filenames: 

The  output  filename,  prefix.cxtension ,  conforms  with  the  GRASS  limit  of  14  characters.  The  entire 
prefix  name  is  used,  a  inserted,  and  as  much  of  the  extension  name  is  used  as  the  14-character  limit 
will  permit.  Excess  characters  are  truncated.  To  minimize  the  possibility  of  creating  output  files  with 
the  same  names  (resulting  in  loss  of  data  from  the  DXF  file),  use  the  prefix  option  to  abbreviate  the 
DXF  file  name.  This  leaves  the  majority  of  characters  available  for  distinguishing  layer  names. 

Translation: 

This  data  translation  program  does  not  contain  any  erf  the  quality  control  functions  available  in  v. digit 
that  will  prevent  data  in  an  improper  format  from  being  input  to  a  GRASS  data  base.  If  present,  DXF 
entities  are  placed  in  output  file(s)  corresponding  to  the  layers  on  which  they  occurred  in  the  DXF 
design  file  input. 

Editing: 

If  the  user  asks  v.in.dxf  to  output  ASCII  vector  ( dig_ascii )  files,  they  must  be  converted  to  binary 
vector  format  before  they  are  usable  by  most  GRASS  vector  commands.  The  user  can  convert  GRASS 
vector  files  from  ASCII  to  binary  format  by  n inning  such  programs  as  v .support  or  vAn.ascii.  After 
conversion  to  binary  format  the  vector  files  can  be  displayed  (e.g.,  with  d.vecl)',  however,  the  user 
must  run  v. support  on  the  binary  vector  files  before  they  can  be  edited  in  v.digit.  The  files  output  by 
v.in.dxf  will  preserve  the  data  in  whatever  form  they  exist  in  the  DXF'  file.  This  means  that  output  files 
may  contain  unsnapped  nodes,  overshoots,  gaps,  ;uid  replicated  lines.  The  data,  and  the  fiie  header 
information  (including  the  owner's  name,  map’s  name,  date,  and  scale,  and  UTM  zone)  for  the  GRASS 
vector  files  output  may  require  editing  by  the  user  in  v.digit. 

Attributes: 

The  v.in.dxf  program  attaches  attributes  only  to  DXF  text  data  that  are  converted  to  GRASS  vector 
data  (such  as  contour  line  labels).  Attributes  are  not  attached  to  converted  DXF  line  data.  For  each 
layer  of  text  data  in  the  DXF  design  file,  v.in.dxf  generates  a  vector  file  consisting  of  rectangular  boxes 
(lines)  that  are  drawn  around  the  DXF  text  data,  and  uses  the  text  values  to  create  a  GRASS  attribute 
file  for  the  boxes.  The  vector  and  attribute  files  can  then  lie  used  to  label  contour  lines  with  the 
v.cadlabel  program. 
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SEE  ALSO 

v.cadlabel,  vutigit,  v.m.ascti,  v.oul.dxf,  vjupport 
AUTHORS 

Original  dxf2dig  program  written  by  Chuck  Fhlschlaeger,  U.S.  Army  Construction  Engineering 
Research  Laboratory  (6/89) 

Revised  by  David  Gerdes,  U.S.  Army  Construction  Engineering  Reseach  Laboratory  (12/89) 

Revised  and  appended  by  Jan  Moorman,  U.S.  Army  Construction  Engineering  Research  Laboratory 
(7/90) 

Code  for  arcs  and  circles  from  National  Park  Service,  CHS  Division,  written  by  Tom  Howard 
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NAME 

vJn.tiger  -  Imports  Census  Bureau  line  data  (TIGER  files)  to  GRASS  vector  format. 
(GRASS  Vector  Data  Import  Program) 

SYNOPSIS 

vJn.tiger 
vJn.tiger  help 

vJn.tiger  dbname=7uzm  inlfilc=nm  in2file  name  zon t=value 


DESCRIPTION 

vJn.tiger  imports  Census  line  data  (called  TIGER)  and  creates  a  "master"  binary  vector  file  containing 
a  large  amount  of  data.  Various  map  layers  can  then  be  created  by  querying  information  from  the 
master  vector  file  using  v.dh.rim  or  one  of  the  Gen.  shell  scripts  listed  in  the  SEE  AESO  section, 
below.  The  database  name  ( dbname )  given  on  the  command  line  will  be  the  n;une  of  the  rim  data 
base,  and  the  master  vector  file  in  GRASS  will  be  named  "dbname. Master”.  'Ilie  master  vector  file  will 
include  till  information  from  the  typel  and  type2  '11GIR  files  given  on  the  comm. u id  line  as  inljiie  and 
in2fde.  If  the  user  simply  types  v.in.tiger  cm  the  command  line,  all  parameters  will  lie  queried  using 
the  stand. ird  GRASS  parser  described  in  tlie  manual  entry  for  parser. 


COMMAND  LINK  OPTIONS 
Parameters: 


dbname  name 
inlfil  e=name 
in2fil  t=name 
zon  e=value 


Vector/rim  data  name  (with  a  maximum  of  seven  characters). 

TIGER  typel  input  file  name. 

TIGIiR  type2  input  file  name. 

Universal  Transverse  Mercator  (UTM)  zone  in  which  these  data  are  located. 
Options:  -60  -  60 


NOTES 

TIGER  data  are  presented  in  latitude^ ongitude  format,  and  are  converted  to  UIM  coordinates  as  part  of 
this  importing  routine.  The  spheroid  used  in  the  conversion  is  dark  66,  as  it  is  the  most  consistent  with 
the  original  data. 


This  command  must  be  compiled  separately,  and  requires  the  use  of  rim  and  v.dh.rim,  which  contain 
FORTRAN  code.  The  user  must  have  access  to  a  FORTRAN  compiler  in  order  to  compile  and  use  this 
command,  since  it  calls  both  rim  and  v.dh.rim.  It  resides  under  sre alpha. 

If  the  user  does  not  know  the  UIM  zone  for  this  data  input  file,  the  command  nUiger .region  should  lie 
run  first  to  determine  the  zone. 


v support  must  be  run  separately  on  the  output  file  if  needed. 

FILES 

Source  code  for  RIM  is  located  under  $GISBASE/../src.rdated/fim 

Source  c<xle  for  v.dh.rim  is  located  under  $ GISBASE/../src . garden^ rass.rinVv.<.lli. rim 

Source  code  for  vJn.tiger  is  located  under  SGISBASE/../s^c.garden/grass.tigerA■  jn.tiger 

Source  c<xle  for  nutiger. region  is  located  under  SGISBASE/../src.garden4»rass.tigcr/ni.tiger.region 

SEE  ALSO 

Gen.Maps,  GenJractmap,  nutiger. region,  v.db.rim,  tiger  .info jh,  and  parser 

AUTHOR 

James  IEnthome  and  David  Satnik,  GIS  lab,  (Central  Washington  University,  Hlensbuig,  WA 
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NAME 

v.mkgrid  -  Creates  a  (binary)  GRASS  vector  map  of  a  user-defined  grid. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.mkgrid 
v.mkgrid  help 

v.mkgrid  map— name  grid  =rows, columns  coordinate -=jt,y  box  =Jength, width 
DESCRIPTION 

v.mkgrid  will  create  a  binary  format,  vector  map  representation  of  a  regular  coordinate  grid. 

Parameters: 

map  mime  Name  to  be  assigned  to  binary  vector  map  layer  output. 

grid  =rows, columns  Number  of  ROWS  and  COLUMNS  to  appear  in  grid. 

coordinate -x,y  lower  left  LASTING  and  NORTHING  coordinates  of  vector  map  layer 

output. 

box  -length, width  I J-T4GTI I  and  WIDTH  of  boxes  in  grid. 

If  the  user  simply  types  v.mkgrid  cm  the  command  line  without  specifying  parameter  values,  the 
program  will  prompt  the  user  for  inputs  using  the  standard  interface  described  in  the  manual  entry  for 
parser. 

NOTES 

The  new  binary'  vector  map  output  is  placed  under  the  dig  directory  in  the  user's  current  mapset,  and 
can  be  ased  like  any  vector  map  layer.  Run  vjupport  to  build  the  topology  information  for  the  vector 
map  before  using  vjnkgrid  map  layer  outputs  in  the  v. digit  program. 

Since  the  grid  is  computer-generated,  the  comer  coordinates  will  be  exact  and  can  be  used  when 
patching  together  several  vjnkgrid  grids. 

This  is  NOT  to  be  ased  to  generate  a  vector  map  of  USGS  quadrangles,  because  USGS  quads  arc  no 
exact  rectangles.  To  generate  a  vector  map  of  USGS  quads,  use  the  program  vjnkquads. 

Ihe  program  ignores  the  current  GRASS  geographic  region  settings.  It  will  create  the  complete  grid 
even  if  part  of  this  grid  falls  outside  the  current  geographic  region. 

SEE  ALSO 

v. digit,  v.mkquads,  v. patch,  vjupport  and  parser 

AUTHOR 

Michael  Higgins,  U.S.  Anny  Construction  Engineering  Research  Laboratory 
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NAME 

vjnkquads  -  Creates  a  GRASS  vector  map  layer  and/or  sites  list  and/or  geographic  region  definition 
file  for  a  USGS  7.5-minute  quadrangle. 

(GRASS  Vector  Program) 

SYNOPSIS 

vjnkqaads 

vjnkquads  help 

vjnkquads  [ta-n]  map  =name 

DESCRIPTION 

There  are  three  types  of  output  available  from  the  GRASS  program  v.mkquads: 

(1)  a  vector  map  of  all  the  full  USGS  quadrangles  that  will  fit  within  the  boundaries  of  the  current 
geographic  region. 

(2)  a  GRASS  sites  list  containing  the  corner  coordinates  of  each  of  these  quads. 

(3)  GRASS  geographic  region  definition  files  associated  with  each  of  the  quads  created. 

A  quad  is  defined  as  the  area  covered  by  a  USGS  7 5- minute  (1:24, 0(X))  map.  This  program  is  useful 
for  managing  a  GRASS  data  base  IjOCATION,  which  contains  a  number  of  quads  that  are  to  be 
patched  together. 

Flags: 

— e  Encompass  current  geographic  region  with  quads  (rather  than  only  creating  those  quads 

that  lie  inside  erf  the  geographic  region).  Use  of  this  optical  will  affect  all  output  options. 

-s  Create  a  GRASS  sites  list  file.  The  sites  list  will  contain  all  the  comer  coordinates  of 

all  the  full  quads  that  can  be  built  in  the  current  geographic  region.  The  sites  list  file 
can  then  be  displayed  using  the  dsites  program. 

-t  Create  region  file(s):  quad.l  quad 2  ...  The  program  will  generate  a  separate  geographic 

region  definition  file  for  each  quad;  each  of  the  geographic  region  files  created  will 
have  the  prefix  quad,  with  some  number  attached  to  it.  For  example,  if  only  one  quad 
were  created,  the  geographic  region  file  quad.l  would  also  be  created  in  the  windows 
director.'  under  the  user’s  current  mapset.  To  make  the  program  generated  geographic 
region  definition  file  quad.1  your  current  geographic  region  setting,  run  the  GRASS 
g.region  pregram. 

—v  Create  vector  file  (default).  Only  full  quads  will  be  created.  The  binary  vector  map 

layer  output  is  placed  under  the  user’s  dig  directory  and  can  be  used  like  any  other 
vector  map  layer.  Run  v support  to  build  the  topology  information  for  the  vector  map 
before  using  v.mkquads  map  layer  outputs  in  the  v. digit  program.  Since  live  quads  are 
computer-generated,  the  comer  coordinates  will  be  exact.  This  simplifies  digitizing  if 
one  or  more  quad  sheets  will  have  to  be  brought  together  for  a  data  base,  because  all  of 
the  quad  comer  points  to  be  joined  will  be  guaranteed  to  match. 

—x  Create  a  GRASS  registration  (reg)  file. 


Parameter: 

map  =name  The  name  of  a  file  to  contain  program  output. 

If  the  user  runs  vjnkquads  without  including  program  parameter  value  and  desired  flags  on  the 
command  line,  the  program  will  prompt  the  user  for  the  above  information  usiig  the  stamlard  GRASS 
interface  described  in  the  manual  entry  for  parser. 
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NOTES 

All  output  options  can  lie  used  on  the  command  line  at  the  same  time.  A  listing  erf  all  the  quad  pants 
in  latitude/longitude  and  UlM  coordinates  will  be  displayed  each  time  the  program  is  executed.  The 
spheroid  being  used  for  the  lat/lon  to  Ul’M  conversions  is  clark66. 

BUGS 

Currently,  this  program  only  works  for  GRASS  locations  in  a  Universal  Transverse  Mercator  (UTM) 
coordinate  system  (in  meters).  There  are  no  guarantees  that  v jnkquads  will  function  properly  if  a 
quadrangle  crosses  U1M  zones.  This  program  has  not  been  tested  outside  the  northwest  UTM 
quadrant. 

SEE  ALSO 

d.sites,  g.region,  v. digit,  v.mkgrid,  v. support  and  parser 
AUTHORS 

Michael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Marilyn  Ruiz,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v. out. arc  -  Converts  GRASS  vector  files  to  ARC/INFO s  "Generate"  file  format. 

(GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out  jitc 
v .out  jvc  help 

v.  out  jut  type  -name  vect  name  arcprcfix  --name 
DESCRIPTION 

v. out. arc  is  a  GRASS  data  export  program  that  converts  files  in  GRASS  vector  format  to  ARC/INI  Os 
"Generate"  tile  fonnat.  Tlie  companion  program  v.in.arc  imports  data  in  ARC/INR>'s  "Generate" 
fonnat  and  converts  them  to  GRASS  vector  fonnat. 

This  program  can  be  run  either  non-interactively  or  interactively.  Ihe  program  will  be  run  non- 
interactively  if  the  user  specifies  parameter  values  on  the  command  line  using  the  following  format: 

v.out  jure  type  name  vect  =name  arc_prefix  =name 

Alternately,  the  user  can  simply  type: 

v.out  jure 

on  the  command  line;  in  this  case,  the  program  will  prompt  the  user  for  parameter  values. 

Parameters: 

type  name  Coverage  (feature)  type. 

Options:  polygon,  line 

vect  =name  Ihe  name  of  a  GRASS  vector  file  to  be  converted  to  ARC/INFO  format, 

are  prefix  name  A  prefix  to  be  assigned  to  the  ARC/LNI-OTormat  files  output  by  v.out. arc. 

INTERACTIVE  MODE:  USER  PROMPTS 

v. out. arc  will  prompt  the  user  to  enter  the  name  of  a  GRASS  vector  file  to  be  exported  to  ARC/INFO 
and  for  a  filename  prefix  to  be  used  in  naming  the  files  created  by  the  program. 

A  GRASS  vector  file  to  be  exported  to  ARC/INFO  must  either  contain  only  linear  features  (i.e.,  have 
only  line  coverage)  or  contain  only  area  edge  features  (i.e.,  have  only  polygon  coverage),  v.out. arc 
w-ill  begin  by  asking  the  user  which  type  of  coverage  (line  or  polygon)  is  to  be  imported: 

COVERAGE  TYPE 
Enter  "polygon"  or  "line" 

Hit  RETURN  to  cancel  request 
> 

The  program  then  prompts  the  user  for  the  name  of  the  GRASS  vector  file  to  be  converted  to 
ARC/INFO  format: 

VECTOR  (DIGIT)  FIIJ5NAME 
Enter  ’list’  for  a  list  of  existing  binary  vector  files 
Hit  RETURN  to  cancel  request 
> 
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Next,  the  user  is  asked  for  a  file  name  prefix  to  be  used  in  naming  the  output  ARC/INFO  Generate 
format  files: 

ARC/INFO  (GENERATE)  FILENAME  PREFIX 
Hit  REIURN  to  cancel  request 

> 

lhe  filename  prefix  will  be  used  to  name  the  various  files  that  will  be  created  for  export  to  ARC/INFO. 
When  labeled  polygon  coverage  data  are  exported,  three  such  files  will  be  created:  a  lines  file  with  the 
suffix  .lin,  a  label-points  file  w  ith  the  suffix  Jab,  and  a  label-text  file  with  the  suffix  .txt.  When  line 
coverage  (.lata  arc  exported,  two  such  files  will  be  created:  a  lines  file  with  the  suffix  Jin,  and  a  label- 
text  file  with  the  suffix  .txt.  Export  of  unlabeled  polygon  or  line  coverage  data  will  result  in  creation 
of  a  lines  file  (Jin  suffix)  only.  See  the  DATA  FILE  FORMATS  section  for  more  information  on  these 
files. 

EXAMPLE 

linear  failures  and  polygon  data  are  made  up  of  the  series  of  arcs  (aka,  vectors)  outlining  their 
perimeters,  lhe  ARC/INFO  Users'  Guide,  in  its  discussion  of  the  Ungenerate  command,  explains 
how'  line  and  polygon  coverage  data  can  be  created  from  files  (like  prefixAin  and  prefix.pol )  containing 
tlie  geographic  coordinates  of  these  arcs,  and  from  files  (like  prefixAab)  containing  the  geographic 
cixirdi nates  of  label-points.  Below  is  an  example  that  illustrates  the  creation,  within  ARC/INFO,  of  a 
polygon  coverage  data  file  (named  soils )  from  the  files  soils.pol  and  soilsAab. 

Arc:  GENERATE  SOILS 
Generate:  INPUT  soils.pol 
Generate:  IJNES 
Generating  lines  ... 

Generate:  INPU1  soilsJab 
Generate:  POINTS 
Generating  points  ... 

Generate:  QUIT 
Arc:  _ 

lhe  above  example  would  create  a  polygon  coverage  data  file  named  soils  with  label-points.  lhe 
label-points  would  have  II)  numbers  that  correspond  to  the  GRASS  category  values  for  the  polygons  in 
file  coverage.  The  INFO  portion  of  ARGTNFO  can  be  used  to  associate  these  label-point  ID  numbers 
with  descriptive  text  from  the  soilsJxt  file. 

DATA  FILE  FORMATS 

I JNES  FILE,  also  know  as  prefixAin  or  prefix.pol  file: 

Ihis  text  file  is  a  "Generate”  format  lines  file.  The  lines  option  of  the  ARC/INFO  Generate  command 
can  be  used  to  read  this  file  into  ARC/INFO.  Each  line  in  the  file  has  a  unique  line-ID  number. 

101 

223343.62  218923.15 
223343.62  222271.06 
25956531  222271.06 
25956531  19557737 
END 
102 

237862.53  20339237 
244970.75  20374428 
253137.66  19557737 
25956531  19557737 
FND 
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103 

23786253  20339237 
23786253  20374438 
223343.62  21839237 
END 

104 

239072.44  186200  56 
23786253  18741050 
23786253  203392  37 
END 
END 

LABEL  POINTS  FTI1%  also  known  as  prefixJab  file: 

This  text  file  will  be  created  by  v.out.arc  if  the  sector  file  being  exported  represents  a  polygon 
coverage,  prejix.lab  consists  of  a  list  of  label-point  (x,y)  oxrrdi  nates,  each  with  a  unique  label-point 
ID  number. 

1  242777.81  211533.09 

2  24345837  199282  38 

3  24345837  195199.28 

1  ABEDTEXr  FILE,  also  known  as  prefix.txt  file: 

In  the  case  of  polygon  coverage  data,  th:s  file  associates  an  integer  category  value  and  a  category  label 
("attribute")  text  string  (containing  no  spaces)  with  each  label-point  ID  number.  In  the  case  of  line 
coverage  data,  this  file  associates  an  integer  category  value  and  an  attribute  text  string  with  each  line-ID 
number. 

The  first  column  is  the  row  number  (which  is  arbitrary  ),  the  second  column  contaias  the  category  value, 
the  third  column  holds  the  line  or  label-point  ID  number,  and  the  fourth  column  contains  the  attribute 
text  string. 


14  1  Coniferous 

2  5  2  Deciduous 

3  2  3  Rangeland 

SEE  ALSO 

v.in.arcf  v support 

AUTHOR 

David  Johnson 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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NAME 

v. out. ascii  -  Converts  a  binary  GRASS  vector  map  layer  into  an  ASCII  GRASS  vector  map  layer. 
(GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out-ascii 
v. out  .ascii  help 

v.out^tscii  input  name  output  =name 
DESCRIPTION 

v. out. ascii  converts  a  GRASS  vector  map  in  binary  format  to  a  GRASS  vector  map  in  ASCII  format. 

The  program  can  be  nm  non- interactively  if  the  user  specifies  all  needed  program  arguments  on  the 
command  line,  in  the  form 

v.out jiscii  input  =name  output  =name 

Parameters: 

input  =name  Name  of  the  binary'  GRASS  vector  input  file  to  be  converted  to  ASCII  formal, 

out (>ut  -name  Name  of  the  ASCII  GRASS  vector  output  file. 

If  the  user  runs  v. out. ascii  without  giving  the  names  of  an  input  and  output  tile  on  the  command  line, 
the  program  will  prompt  the  user  for  these  names. 

NOTES 

The  GRASS  program  v.in.ascii  performs  the  function  of  v.oui.ascii  in  reverse;  i.e.,  it  converts  vector 
files  in  ASCII  format  to  their  binary  format.  These  twr  companion  programs  are  useful  both  for 
importing  and  exporting  vector  files  between  GRASS  ana  other  software,  and  for  transferring  data 
between  machines. 

The  output  from  v.  out.  ascii  will  be  placed  in  the  user’s  current  mapset  under  the 
SIDCATION/dig^ascii  directory. 

v.out.ascii  does  not  copy  the  dig_cats  file  associated  with  the  binary  vector  input  map  to  the  ne  ’ 
output  file  name.  The  user  must  copy  the  dig_cats  file  to  the  new  output  name  if  this  is  desired  (e.g., 
using  the  UNIX  c ,  oinmand). 

SEE  ALSO 

v.digu,  v.impo,  t,  v.in.c  ii,  v support 

Alii  DRS 

*  fichael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
james  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v.out.dlg  -  Converts  binaiy  GRASS  vector  data  to  binary  DIG- 3  Optional  vector  data  format. 

(GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out.dlg 
v.  out  .dig  help 

v.out.dlg  input  name  output  name 
DESCRIPTION 

The  GRASS  program  v.out.dlg  allows  the  user  to  convert  GRASS  vector  data  to  DLG-3  Optional 
format,  for  export  to  other  systems. 

The  user  can  run  the  program  non-interactively  by  specifying  all  program  arguments  on  the  command 
line,  in  the  form: 

v.out.dlg  input  =name  output  name 
Parameters: 

input  =name  Name  of  the  binaiy  GRASS  vector  data  file  to  be  converted  to  DLG-3  format. 

output  name  Name  to  be  assigned  to  the  DLG-3  Optional  format  output  file  created. 

If  the  user  does  not  give  the  names  of  an  input  and  output  file  on  the  command  line,  the  program  will 
prompt  the  user  to  enter  these  names. 

NOTES 

The  v. out. dig  program  requires  that  the  input  vector  map  layer  have  full  topological  information 
associated  with  it.  This  means  that  the  GRASS  program  v support  should  have  been  the  last  program 
to  have  effected  any  changes  upon  the  vector  map  layer  before  it  is  run  through  v. out. dig.  If  this  is  not 
the  case,  v.out.dlg  will  terminate  with  a  message  that  v. support  needs  to  be  run. 

The  output  from  v. out. dig  will  be  placed  in  SLOCATION/dlg. 

SEE  ALSO 

v.import,  vJn.ascii,  v.in.dlg,  v support 

AUTHOR 

David  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v.out.dxf  -  GRASS  vector  format  to  DXF  format  conversion  program. 

(GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out.dxf 
v.out.dxf  help 

v.out.dxf  input  =name  output  name 
DESCRIPTION 

The  GRASS  program  v.out.dxf  conversion  program  generates  an  ASCII  DXF  (AutoCad)  file  from  a 
GRASS  vector  ASCII  file.  The  output  file  is  placed  in  the  user’s  current  working  drectory  unless  the 
user  specifies  a  full  pathname  for  the  output. 

Parameters: 

input  name  The  name  of  an  existing  GRASS  vector  ASCII  file. 

output  =name  Name  to  be  assigned  to  the  DXF  output  file. 

NOTH:  DXF  files  output  by  AutoCad  have  tire  suffix  .dxf 

NOTES 

This  program  does  not  currently  read  in  binary  files. 

Ibis  program  remains  under  alpha  testing.  It  resides  in  the  src. alpha  directory  and  must  be  compiled 
separately  by  the  user. 

SEE  ALSO 

v.cadlabel,  v.digit,  v.in.ascii,  v.in.dxf,  v support 
AUTHOR 

Chuck  Fhlschlaeger,  U.S.  Army  Construction  Engineering  Research  Laboratory,  wrote  original 
v.out.dxf  program  in  April  1989. 


GR ASS  4.0  (Summer  1991) 


US.  Army  CFRI 


413 


v. out  .moss 


GRASS  Reference  Manual 


V.OUtjnoSS 


NAME 

v. out. moss  -  Converts  GRASS  site,  line,  or  area  data  into  MOSS  import  format. 

(GRASS  Vector  Data  bjeport  Program) 

SYNOPSIS 

v.outjmoss 

DESCRIPTION 

This  program  produces  a  MOSS  import  file  containing  GRASS  site,  line,  or  area  features  that  have  been 
converted  into  MOSS  point,  line,  or  polygon  features,  respectively.  Only  one  type  of  data  (site,  line,  or 
area)  can  be  converted  at  a  time.  Site  data  can  be  extracted  from  GRASS  site  lists  files  or  vector 
files,  at  the  user's  discretion.  The  resultant  MOSS  files  will  be  created  in  the  moss  subdirectory  of  the 
current  mapset. 

The  user  will  be  prompted  for  the  GRASS  data  ty  pe,  the  name  of  the  site  lists  or  vector  file  to  be1 
converted,  and  the  name  of  the  the  MOSS  import  file  to  Ire  created.  If  line  data  is  being  converted,  the 
user  will  be  asked  whether  area  edges  should  be  processed  as  lines.  If  so,  the  line  features  produced 
from  the  area  edges  will  not  Stave  attributes  associated  with  them. 

Upon  successful  completion  of  the  tlata  export,  the  number  of  items  converted  will  Ire  printed,  and  the 
user  will  be  given  the  option  of  processing  another  GRASS  file. 

NOTES 

Vector  data  cannot  be  exported  until  the  necessary  GRASS  support  files  have  been  built. 

This  program  is  interactive  and  requires  no  command  line  arguments. 

SEE  ALSO 

v  support 

AUTHOR 

Chris  Emmerich,  Aitometric,  Inc. 
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NAME 

v. patch  -  Creates  a  new  binary  vector  map  layer  by  combining  other  binary  vector  map  layers. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.  patch 
v. patch  help 

v. patch  input  =name[name,...\  output  name 
DESCRIPTION 

v. patch  allows  the  user  to  combine  any  number  of  vector  map  layers  together  to  create  one  composite 
vector  map  layer. 

Parameters: 

input  =name,name,  ...  Name(s)  of  input  vector  map(s)  to  be  patched  together. 

output  -^name  Name  assigned  to  composite  "patched"  vector  output  map. 

lhe  program  will  be  run  non-interactively  if  the  user  specifies  the  names  of  the  vector  map(s)  to  be 
patched  and  the  name  of  an  output  file  to  store  the  resulting  composite  patched  vector  map  on  the 
command  line,  in  the  form: 

v .patch  input  =name[ /tame,...]  output  name 

Alternately,  if  the  user  runs  v.patch  without  specifying  input  and  output  file  names  on  the  command 
line  (by  typing  simply  v.patch).  the  program  will  prompt  the  user  for  inputs  using  the  standard  GRASS 
interface  described  in  the  manual  entry  for  parser. 

NOTES 

lhe  vector  map  layers  to  be  patched  together  must  exist  in  the  user’s  current  mapset  search  path,  and 
the  composite  vector  map  layer  name  given  must  not  already  exist  in  the  user’s  current  mapset. 

After  running  v.patch,  the  header  file  will  contain  only  information  taken  from  the  first  input  file  name 
given  in  the  string  input  =name, name,  ...,  with  the  exception  of  the  geographic  region’s  edge 
information,  and  the  scale  and  threshold  information.  (The  user’s  current  geographic  region  settings  ai  ' 
ignored;  this  information  is  instead  extracted  from  the  vector  file  headers.)  In  the  new  composite  vector 
map  layer,  the  boundaries  of  the  geographic  region  will  be  expanded  to  encompass  all  of  the  geographic 
area  included  in  the  map  layers  being  patched,  and  the  scale  will  be  set  equal  to  the  smallest  (i.e.,  most 
gross)  scale  used  by  any  of  the  patched  map  layers  (this  will  affect  default  node-snapping  thresholds), 
lhe  map  threshold  is  calculated  automatically  from  the  map  scales  given  in  the  file  headers,  and 
(currently)  is  not  used  directly.  The  composite  vector  map  layer’s  header  will  probably  need  to  be 
edited;  this  can  be  done  from  within  the  GRASS  program  v. eh  git. 

lhe  GRASS  programs  vjnkgrid  and  vjnkquads  can  be  used  to  ensure  that  the  borders  of  the  maps  to 
be  patched  together  align  neatly. 

Any  vectors  that  are  duplicated  among  the  maps  being  patched  together  (eg.,  border  lines)  will  have  to 
lx  edited  or  removed  after  v. patch  is  run.  Such  editing  can  be  done  using  v. digit. 

After  running  v.patch  the  user  must  run  v  ^support  on  the  composite  vector  map  layer  in  order  to  create 
a  dig_plus  (topology)  file  for  it.  At  this  time,  you  can  request  that  a  very  small  snapping  threshold  be 
used,  to  cause  the  ntxles  that  match  up  across  vector  map  layers  to  snap  together  without  affecting  the 
integrity  of  the  remainder  of  the  vector  map  layer. 

BUGS 

lhe  ehg_cats  and  reg  file  information  for  the  maps  Ixing  patched  together  is  not  copied  to  the 
composite,  patched  map  layer.  The  user  should  therefore  nm  vjupport  on  the  output  file  produced  by 
this  program. 
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SEE  ALSO 

v. digit,  v.in.ascii,  v.mkgrid,  vjnkquads,  v support,  and  parser 
AUTHOR 

Ebvid  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v. prune  -  Prunes  points  from  binary  GRASS  vector  data  files. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.prune 
v  .prune  help 

v.prune  ( -I]  input  =name  output  name  thresh  =vo/ue 
DESCRIPTION 

The  GRASS  program  v.prune  allows  the  user  to  remove  extra  points  from  a  vector  file.  This  allows 
users  to  reduce  disk  space  required  by  a  vector  file  and  still  have  data  accuracy  within  a  given 
tolerance. 

Flag: 

-i  The  pruning  threshold  value  is  specified  in  map  inches,  rather  than  in  data  base 

units  on  the  ground. 

Parameters: 

input  —name  Name  of  binary  GRASS  vector  file  containing  data  to  be  pruned, 

output  =/uune  Name  to  be  assigned  to  new,  pruned  vector  output  file, 
thresh  rvalue  Threshold  value  used  for  pruning. 

The  program  will  be  nm  non- interactively  if  the  user  specifies  all  parameters  and  (optionally)  die  -i  flag 
on  the  command  line,  using  the  form: 

v.prune  [-i]  input  ^narne  output  =name  thresh  =value 

If  the  user  simply  types  v .prune  without  specifying  program  arguments  on  the  command  line,  the 
program  will  prompt  the  user  to  enter  parameter  values. 

NOTES 

Ihe  threshold  value  is  the  same  as  the  v. digit  pruning  threshold.  This  is  specified  in  data  base  units  c.i 
the  ground  (eg.,  in  ground  meters  for  UTM  data  bases).  The  threshold  can  also  be  specified  in  inches 
on  the  map,  and  the  program  will  convert  these  to  data  base  ground  units  using  the  scale  in  the  vector 
file.  If  you  specify  the  scale  in  map  inches  rather  than  in  ground  units,  you  must  specify  that  inches  are 
used  by  setting  the  -I  flag.  The  input  vector  data  layer  will  be  read  and  the  resultant  pnmed  vector  data 
layer  will  be  placed  into  a  newly  created  output  file  whose  name  is  specified  by  the  user,  leaving  the 
original  vector  map  unchanged. 

The  pntning  algorithm  throws  away  redundant  points  within  the  specified  threshold.  It  works  on  each 
vector  separately,  working  from  node  to  node.  It  does  not  change  die  position  or  number  of  nodes. 

SEE  ALSO 

v.digit,  v.in.ascii 

AUTHOR 

Dtivid  Gerdes,  U.S.  Anny  Constmction  Lngineering  Research  Laboratory 
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NAME 

vjpag  -  Process  spaghetti-digitized  binary  vector  file. 

(GRASS  Vector  Program) 

SYNOPSIS 

v-apaR 
▼•sp*g  hdp 

Tjpag  map  =name  [  threshold  =value\ 

DESCRIPTION 

This  program  will  fix  vector  data  that  were  not  digitized  in  correct  GRASS  vector  format.  It  will  create 
a  node  at  even  line  crossing,  and  will  delete  ;dl  hailing  lines  of  length  less  than  the  specified 
threshold. 

COMMAND  LINK  OPTIONS 
Parameters: 

map=name  Name  of  the  binary  vector  file  to  be  fixed 

threshold=value  Node- snapping  threshold  value. 

NOTES 

The  user  must  run  v support  after  running  vjpag  to  correct  the  topology  (dig  plus)  file. 

vjpag  generally  deletes  many  lines  from  the  input  vector  map  layer.  Because  deleted  lines  are  not 
eliminated  from  a  vector  data  (dig)  file,  but  are  only  mttrked  as  deleted,  the  user  w  ill  probably  w  ish  to 
tun  v.clean  on  the  vector  file  after  running  v.spag  to  eliminate  any  deleted  lines  from  the  dig  file  and 
decrease  :ts  size. 

This  program  remains  under  alpha  testing.  It  resides  in  the  sre .alpha  directory  ;md  must  be  compiled 
separately  by  the  user. 

BUGS 

This  program  contains  several  known  bugs.  It  will  sometimes  get  stuck  in  a  loop  in  which  it  creates 
the  same  line  over  and  over  again.  It  will  occasionally  create  an  incorrect  line.  Users  are  strongly 
urged  to  back-up  their  vector  data  files  before  n inning  this  alpha  version  of  vjpag. 

SEE  ALSO 

v.clean,  v.digit,  vjupport 

AUTHOR 

David  Gerdes,  U.S.  Anny  Construction  Engineering  Research  laboratory 
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NAME 

vjtats  -  Prints  information  about  a  binary  GRASS  vector  map  layer. 

(GRASS  Vector  Program) 

SYNOPSIS 

vjtats 

v  .stats  help 

v .stats  [Hi]  map  name 

DESCRIPTION 

The  program  vjtats  will  print  to  standard  output  information  about  a  user-specified  binary  GRASS 
vector  map  layer. 

Hag: 

Hi  Display  header  information  from  the  vector  file. 

Parameter: 

map  =name  Name  of  the  binary  GRASS  vector  file  to  be  queried. 

The  program  will  be  run  non- interactively  if  the  user  specifies  the  parameter  value  and  (optionally)  sets 
the  h  flag  on  the  command  line,  using  the  form: 

v .stats  [Hi]  map=name 

If  the  user  instead  simply  types  v .stats  without  specifying  program  arguments  on  the  command  line, 
the  program  will  prompt  the  user  to  enter  inputs  through  the  standard  user  interface  described  in  the 
manual  entry  for  parser. 

NOTES 

Sample  output  follows: 

Format:  Version  4.0  (Level  2  access)  (Portable) 

Number  of  Lines:  3 

Number  of  Nodes:  2 

Number  of  Areas:  2  (complete) 

Number  of  Isles:  1  (complete) 

Number  of  Atts  :  2 

The  GRASS  version  number  is  given.  Parenthetical  text  following  this  describes  the  read  access  level 
available  and  notes  whether  or  not  the  file  is  in  GRASS  version  4.0  portable  data  format.  The  access 
level  indicates  the  types  of  data  available  for  the  named  vector  map  layer.  "Level  1"  denotes  a  binary 
vector  file  (without  any  accompanying  dig_plus  file),  while  "Level  2”  denotes  the  existence  of  a 
t Ug_plus  (vector  topology)  file  for  the  named  map  layer  (generally  created  by  v support).  If  only 
Level  1  information  is  available  for  a  vector  map  layer,  only  the  number  of  lines  and  (optionally)  the 
file  header  will  be  printed  to  standard  output. 

If  all  areas  and  islands  (isles)  in  the  vector  file  have  been  identified  (usually  by  vjupport),  their  counts 
will  be  followed  by  "complete!'  If  not,  they  will  be  followed  by  "inconplete."  The  d lg_plus  file, 
which  is  created  and  updated  by  vjupport,  must  exist  for  this  information  to  be  output. 

SEE  ALSO 

v. digit,  v.import,  vjupport,  and  parser 

AUTHOR 

David  Gerdes,  U.S.  Anny  Constmction  Engineering  Research  Laboratory 
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NAME 

vjupport  -  Creates  GRASS  support  files  for  (binary)  GRASS  vector  data 
(GRASS  Vector  Program) 

SYNOPSIS 

▼.support 
▼.support  help 

v .support  [-sprj  mup  name  [option  -name]  [threshold  =value] 

DESCRIPTION 

vjupport  builds  GRASS  support  files  for  (binary)  GRASS  vector  data  files.  These  support  files  supply 
topology  ( dig_plus )  and  category  (dig_att)  information  that  are  needed  by  other  GRASS  programs 
(eg.,  by  v. digit,  v.to.rast,  etc.). 

The  program  gives  the  user  the  options  of:  (1)  building  topological  information  (the  digplus  file) 
needed  by  v. digit  for  the  vector  data  file,  and/or  (2)  editing  the  category  label  ( dig_cats )  file  associated 
with  the  vector  data  file. 

OPTIONS 

Program  parameters  and  flags  have  the  following  meanings. 

Flags 

-a  Snap  nodes.  Valid  only  with  build  option. 

-p  Prompt  user  for  threshold  value.  Valid  only  with  build  option.  This  flag  is 

designed  to  be  used  only  by  the  v. import  program,  and  can  usually  be  ignored. 

-r  Reset  comers  of  map  region  from  range  of  data  values. 

Parameters: 

map  =name  Name  of  binary  GRASS  vector  data  file  for  which  support  files  are  to  be  created 

or  modified.  This  map  layer  must  exist  in  the  user’s  current  GRASS  mapset. 

option  =name  Build  topology  information  ( dig_plus  file),  or  edit  categories  (dig_jatt  file)  for 
map. 

Options:  build,  edit 
Default:  edit 

threshold  =value  Snapping  threshold  value  to  be  used  when  building  topology.  Valid  only  with 
build  option  and  -s  flag. 

The  user  can  run  this  program  non- interactively  by  specifying  parameter  values  (and  optionally,  flag 
settings)  on  the  command  line. 

Alternately,  the  user  can  simply  type  the  command  ▼  .support  on  the  command  line.  In  this  event,  the 
program  will  prompt  the  user  to  enter  parameter  values  and  flag  settings. 

If  the  build  option  is  chosen,  the  user  may  further  specify  the  -s  flag,  to  snap  nodes  in  the  vector  file. 
If  nodes  are  to  be  snapped,  the  user  can  either  (1)  use  the  calculated  default  threshold  (based  on  the 
scale  of  vector  data);  (2)  enter  the  -p  flag,  causing  the  program  to  prompt  the  user  for  a  snapping 
threshold  value;  or  (3)  enter  a  specific  threshold  value  on  the  command  line. 

The  spatial  assignment  of  category  values  (found  in  the  dig_att  file)  is  also  performed  during  building 
of  file  topology. 

The  edit  option  allows  the  user  to  edit  the  category  labels  to  be  associated  with  the  categoty  values 
attached  to  the  vector  data  during  topology  building.  These  labels,  if  created,  are  then  used  for  raster 
map  layers  derived  from  their  vector  counterparts.  The  labels  are  placed  in  the  dig_cats  directory. 
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NOTES 

A  dig_plus  file  must  be  created  for  each  imported  vector  map  before  it  can  be  used  in  post- GRASS  3.0 
versions  of  digit  (now  referred  to  as  v. digit). 

Topological  information  for  GRASS  vector  files  can  also  be  built  using  option  4  erf  the  v  .import 
program. 

This  program  will  convert  pre-4.0  version  GRASS  vector  files  to  4.0  format. 
v support  creates  support  files  only  for  binary  vector  files  located  in  the  user’s  current  mapset. 

SEE  ALSO 

v.digit,  v. import,  v.in.ascii,  v.prune,  v.to.rast 

AUTHORS 

David  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
Michael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

vjo.rast  -  Converts  a  binary  GRASS  vector  map  layer  into  a  GRASS  raster  map  layer. 

(GRASS  Vector  Program) 

SYNOPSIS 

v.toj'ast 
v.torast  help 

T.torait  input  =name  output  =name 
DESCRIPTION 

vjo.rast  transforms  (binary)  GRASS  vector  map  layers  into  GRASS  raster  map  layer  format.  Most 
GRASS  analysis  programs  operate  on  raster  data. 


Parameters: 

input  -name  Name  of  the  binary  vector  map  layer  to  be  converted, 

output  ^name  Name  to  be  assigned  to  the  raster  map  layer  output. 

The  user  can  nm  the  program  non-interactively  by  specifying  the  names  of  a  vector  input  file  and  raster 
output  file  on  the  command  line,  using  the  form: 

v-toarast  input  =name  output  —name 

If  the  user  instead  types  simply  ▼.toxast  cm  the  command  line,  the  program  will  prompt  the  user  to 
enter  these  names. 

NOTES 

vjo.rast  will  only  affect  data  in  areas  lying  inside  the  boundaries  of  die  current  geographic  region. 
Before  running  v.to.rast,  the  user  should  therefore  ensure  that  the  current  geographic  region  is  correctly 
set  and  that  the  region  resolution  is  at  the  desired  level;  the  program  may  otherwise  create  an  empty 
raster  map  layer.  An  empty  raster  map  layer  will  also  be  created  if  the  vector  map  layer  has  not  been 
assigned  category  /attribute  labels  (eg.,  through  use  of  the  v.digit  program). 

The  v.to.rast  program  creates  two  files:  a  raster  map  layer,  and  a  history  file.  The  GRASS  program 
r. support  must  be  non  to  create  additional  support  files  for  the  raster  map. 

Additional  problems  sometimes  lead  to  the  creation  of  empty  raster  map  layers.  Unfortunately,  error 
messages  explaining  these  phenomena  do  not  yet  exist. 

SEE  ALSO 

g.region,  r support,  v.digit,  v.import,  v support 

AUTHORS 

Michael  Higgins,  U.S.  Army  Construction  Engineering  Research  Laboratory 
David  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

v.toMtes  -  Converts  point  data  in  a  binary  GRASS  vector  map  layer  into  a  GRASS  siteJists  file. 
(GRASS  Vector  Program) 

SYNOPSIS 

v.to.sites 
v.to.sites  help 

v.to.sites  input  name,  output  name 
DESCRIPTION 

The  v.to.sites  program  extracts  site  data  from  a  GRASS  vector  map  layer  and  stores  output  in  a  new 
GRASS  siteJists  file.  The  resulting  sites  map  layer  can  be  used  with  such  programs  as  duties.  Oily 
site  (point)  features  in  the  named  vector  map  layer  are  extracted  and  placed  into  the  resulting  site  list. 
Lines  and  areas  in  the  vector  file  arc  ignored. 

The  user  can  run  the  program  non- interactively  by  specifying  the  names  of  an  existing  vector  input 
map  layer  and  a  new  site  list  file  to  be  output  on  the  command  line.  The  program  will  be  run 
interactively  if  the  user  types  v-to-sites  without  arguments  on  the  command  line.  In  this  case,  the  user 
will  be  prompted  to  enter  parameter  values  through  the  standard  user  interface  described  in  the  manual 
entry  for  parser. 

Parameters: 

input  name  Name  of  an  existing  binary  vector  map  layer  from  which  site  data  are  to  be 

extracted. 

output  =name  Name  to  be  assigned  to  the  resultant  siteJists  file. 

If  any  of  the  sites  have  been  labeled  in  vjhgit,  then  the  resultant  site  list  will  contain  category 
information.  If  none  of  the  sites  are  labeled,  a  binary  (0/1)  site  list  file  will  be  produced. 

SEE  ALSO 

d.sites,  s.db.rim,  s.menu,  vjdb.rim,  v. digit  and  parser 
AUTHOR 

David  Gerdes,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

vJransform  -  Transforms  an  ASCII  vector  map  layer  from  one  coordinate  system  into  another 
coordinate  system. 

(GRASS  Vector  Program) 

SYNOPSIS 

▼.transform 
▼.transform  help 

▼.transform  [— y]  input  nartu  output  =name  [pointsrfile  name] 

DESCRIPTION 

This  program  has  been  used  to  import  vector  files  that  were  in  scanner  or  digitizer  (x  ,y)  coordinates  and 
to  transform  these  into  UIM  coordinates. 


Flag: 

-y 

Parameters: 
inpot  =name 
output  -  name 
rointsGle  =mame 


Suppress  the  printing  of  residuals  or  other  information  to  standard  output. 


Name  of  the  ASCII  vector  map  layer  to  be  transformed. 

Name  to  be  assigned  to  the  resultant  (transformed)  ASCII  vector  map  layer. 

Name  of  a  file  containing  transformation  points,  whose  format  is  given  below. 
Give  a  full  path  name  for  this  file  or  it  will  be  assumed  to  be  1  orated  in  the  user’s 
current  directory. 


The  user  can  run  this  program  non-interactively  by  specifying  parameter  values  (and  „  ptionally,  the  flag 
setting)  on  die  command  line. 

If  the  user  runs  T-tr.nsform  without  specifying  program  arguments  on  the  command  line,  the  program 
will  prompt  the  user  for  inputs.  When  the  rugram  prompts  the  user  for  two  sets  of  transformation 
points,  the  first  set  of  points  entered  by  the  user  should  be  in  the  coxrdinate  system  of  the  input  map, 
and  the  second  set  of  points  shoxild  represent  the  corresponding  geographic  points  in  the  coordinate 
system  into  which  the  map  will  transformed.  A  user  must  enter  4  to  10  of  each  set  of  points  for  the 
transformation  to  work  correctly. 

After  the  user  has  entered  both  sets  of  points,  the  program  will  show  the  amount  of  error  associated 
with  the  transformation  of  the  given  points  as  the  residual  mean  average  (RMS).  (An  acceptable 
RMS  for  a  T24JOOO  UTM  map  would  be  1.2  to  2.4  (meters).)  It  will  then  ask  if  the  transfomation 
RMS  value  is  acceptable.  After  an  RMS  is  accepted  by  the  user,  v. transform  will  transform  the  ASCII 
( dig_ascii )  vector  map  anoi  its  associated  attribute  (dig^att)  file  into  the  requested  coordinate  system. 

Remember  to  run  v. support  or  v. import  on  the  outpo'  map. 

NOTES 

When  rectifying  a  map  to  another  coordinate  system  using  v .transform,  the  user  shoxild  specify  the 
coordinates  of  between  4  to  10  points,  and  state  these  both  in  the  coordinate  sy  stems  of  the  input  and 
output  maps.  The  two  sets  of  coordinates  can  be  input  to  vJransform  interactively ,  cr  front  a  file 
specified  on  the  command  line  with  the  pointsfile  option.  The  pointsfile  option  is  especially  useful 
when  several  maps  in  the  same  geographic  area  reojuire  transformation,  as  it  eliminates  the  necessity  tor 
the  user  to  repeatedly  type  in  the  same  transformation  coordinates. 

A  pointsfile  file  will  contain  between  4  to  10  lines;  each  line  will  contain  the  set  of  coxroSnate 
transformation  points  for  the  input  map  and  the  corresponding  set  of  coordinates  for  the  output  map. 
The  minimum  number  of  lines  for  the  transformation  to  take  place  is  four. 
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The  format  of  the  pointsfile  file  is  shown  below: 


Input  Map 

Output  Map 

x  y 

x  y 

x  y 

x  y 

x  y 

x  y 

_x _ 

x  Y 

In  the  format  shown  above  the  x’s  and  y’s  can  be  thought  of  as  eastings  and  northings,  depending  on 
what  coordinate  systems  you  are  transforming  to  and  from. 

An  example  of  the  pointsfile  file: 


1 

1 

589000 

4913000 

1 

17000 

589000 

4930000 

17000 

17000 

610000 

4930000 

17000 

1 

610000 

4913000 

Within  the  pointsfile  file,  numbers  on  a  line  must  be  spaced  apart  with  tabs  or  Hanks.  The  example 
shown  above  was  used  to  convert  a  map  in  digitizer  coordinates  (range  of  1-18000)  to  UTM  coordinates 
within  the  UTM  zone  for  the  Spearfish  sample  data  base  location. 

Because  this  pointsfile  file  is  not  your  usual  GRASS  data  file,  the  user  will  have  to  keep  track  of  where 
it  is  on  the  system.  When  the  pointsfile  option  is  used  on  the  command  line  to  input  the 
transformation  points,  the  program  does  not  ask  whether  or  not  everything  is  acceptaHe  before 
converting  the  vector  file  and  the  attribute  file. 

The  user  is  advised  to  mn  this  program  interactively  with  a  specific  set  of  transformation  coordinates 
and  to  examine  the  resulting  residuals,  to  determine  how  accurate  the  transformation  will  be  (i.e.,  pick 
points  with  known  values  in  both  coordinate  systems).  After  the  residuals  are  acceptaHe,  thos< 
transformation  axxxli  nates  can  be  used  with  the  program  run  non-interactively  to  transform  other  map 
in  the  same  geographic  area. 

WARNING 

This  is  a  general -pirpose  program  and  can  be  fooled  into  giving  low  residuals;  i.e.,  low  residual  values 
may  not  necessarily  imply  a  better  resolution  of  ground  coordinates  to  digitizer  coordinates.  It  is 
strongly  suggested  that  any  transformed  map  be  checked  for  accuracy.  The  program  assumes  that  the 
coordinate  systems  will  be  plani metric  and  has  never  been  tested  with  negative  values. 

If  this  pregram  is  being  used  to  transform  maps  from  State  Plane  to  UIM  coordinates,  and  vice  versa; 
users  should  be  aware  of  the  following  points.  This  program  will  work  better  with  State  Plane  zones 
that  use  the  Transverse  Mercator  projection.  Those  are  states  that  have  their  state  zones  splitting  the 
state  vertically,  like  Illinois.  This  program  will  not  work  as  well  with  states  that  use  the  Lambert 
Conformal  Conic  projection.  Those  are  states  that  have  their  state  zones  splitting  the  state  horizontally, 
like  Wisconsin.  It  is  also  best  to  keep  the  area  being  transformed  relatively  small. 

SEE  ALSO 

v. digit,  v. import,  v. support 

AUTHOR 

Michael  Higgins,  U  S.  Annv  Construction  Engineering  Research  Laboratory 
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NAME 

vjrim  -  Trims  small  spurs,  and  removes  excessive  nodes  from  a  binary  GRASS  vector  (dig)  file. 
(GRASS  Raster  Program) 

SYNOPSIS 

v.trim 
v.trim  help 

v.trim  input  =name  output  —name  [trim  =value] 

DESCRIPTION 

vjrim  scans  the  user-specified  GRASS  vector  input  file  and  removes  from  it  all  lines  having  a  length 
less  than  a  user-specified  trimming  factor.  Excess  nodes  (those  unnecessary  to  a  line’s  definition) 
between  line  junctions  are  also  removed.  The  resulting  vector  output  is  sent  to  a  user-named  output 
file;  the  original  vector  input  file  is  not  modified  by  vjrim. 

The  trimming  factor  parameter  (trim  =value)  gives  the  user  control  over  the  size  of  small  spurs  or 
"dangling  lines"  to  be  removed.  The  trimming  factor  is  expressed  in  the  same  units  (map  coordinates) 
as  the  vector  (dig)  data  within  the  user’s  current  GRASS  data  base  LOCATION  (e.g.,  in  meters  for 
UTM  locations,  in  pixels  or  cells  for  locations  in  an  x,y  coordinate  system,  etc.). 

OPTIONS 

The  user  can  run  tins  program  either  non-interactively  or  interactively.  The  progi.an  will  be  run  non- 
interactivdy  if  the  user  specifies  program  arguments  cm  the  command  line,  using  the  form: 

v.trim  input  name  output  =name  [trim  =value] 

If  vector  map  input  and  output  names  are  given  on  the  command  line,  any  other  parameter  values  left 
unspecified  on  the  command  line  will  be  set  to  their  default  values  (see  below).  Alternately,  the  user 
can  simply  type  v-trim  on  the  command  line,  without  program  arguments.  In  this  case,  the  user  will 
be  prompted  for  needed  parameter  values  using  the  standard  GRASS  user  interface  described  in  the 
manual  entry  for  parser. 

Parameters: 

input  name  Name  of  an  existing  vector  map  layer  in  the  user’s  current  mapset  search  path 

containing  lines  to  be  "trimmed." 

output  name  Name  of  a  new  vector  file  to  contain  the  "trimmed”  output. 

trim  =value  A  user- specified  trimming  factor,  denoting  the  length  of  trimmed  lines  in  map 

units.  All  lines  having  a  length  less  than  this  trimming  factor  will  be  "trimmed" 
(i.e.,  removed)  from  the  named  vector  input  file. 

Default:  10  (in  units  of  meters  or  cells) 

NOTES 

v support  must  be  run  on  the  vector  input  file  prior  to  naming  v.trim. 

v support  must  also  be  run  cm  the  resultant  vector  output  file  to  build  the  needed  topology  information 
stored  under  the  user’s  dig_pius  directory. 

r.line  maintaias  the  same  format  (binary  or  ASCII)  and  attribute  ty pc  (linear  or  area  edge)  as  those  of 
the  original  vector  (dig)  input  file. 

A  trimming  factor  of  zero  (0)  will  not  remove  any  small  spurs,  but  will  remove  all  excess  nodes. 

SEE  ALSO 

r.line,  r.thin,  v. digit,  v. import,  v support,  and  parser 

AUTHOR 

Michael  Baba 
DBA  Systems,  Inc. 

10560  Arrowhead  Drive 
Fairfax,  Virginia  22030 
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UNIX  SHELL  SCRIPT  PROGRAMS 


Like  Main  Programs,  UNIX  shell  script  programs  have  received  both  alpha-  and  beta-testing.  However, 
while  other  GRASS  programs  are  written  in  the  “C”  programming  language,  shell  scripts  are  UNIX 
Bourne  and  C-shell  scripts  readily  developable  by  nonprogrammers  and  others  unfamiliar  with  “C.”  Shell 
scripts  are  separately  described  for  the  convenience  of  potential  system  developers  at  GRASS  user  sites, 
who  are  encouraged  to  examine  the  shell  scripts,  located  on-line  in  the  directories  indicated  in  this  manual, 
and  to  develop  their  own  scripts. 
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NAME 

3d.viewjh  -  Displays  several  3-dimensional  views  of  a  landscape  on  the  user’s  graphics  monitor. 
(GRASS  Shell  Script) 

SYNOPSIS 

3d.view.sh 
3d.view.sh  help 

3d.view.sh  fi\e- mapname  ef  —map  name  vh  ^viewing  .height  sv  =sinJc_value  exag  =exag 

If  =4ine_Jrequency  back  =background_color 

DESCRIPTION 

3d.view^h  is  a  Bourne  shell  (sh(l))  script  that  displays  several  3-dimensional  views  of  a  landscape  on 
the  user’s  graphics  monitor.  It  erases  the  graphics  monitor  and  then  prepares  it  for  the  display  of  nine 
equally-sized  frames.  The  user-specified  raster  map  layer  (given  by  fil e^name)  is  displayed  using 
d.rasl  in  the  middle  frame.  The  remaining  frames  are  then  used  to  display  3-d  perspective  views.  The 
top  middle  panel  is  a  view  from  the  north,  the  top  right  from  the  north-east,  the  right  from  the  east,  and 
so  on.  Each  is  drawn  with  a  call  to  the  d.3d  program.  The  viewing  angles  are  calculated 
automatically.  If  options  are  not  staled  on  the  command  line,  default  values  will  be  used.  These  values 
are  listed  under  Parameters,  below. 

Parameters: 

Gle=mapname  Name  of  raster  map  layer  to  be  displayed. 

Default:  elevation 

ef  mapname  Name  of  raster  map  layer  whose  category  values  will  supply  the  elevation  values 

used  to  generate  3-d  perspective  views. 

Default:  elevation 

vh  ^viewing  ^height  Height  (in  meters)  of  the  location  from  which  scores  will  be  viewed. 

Default:  30000 

s \=sink_value  Sink  facto  value,  causing  the  image  to  be  displayed  lower,  or  higher,  on  the 

graphics  screen. 

Default:  0 

exag  ^vertical  exaggeration 

Vertical  exaggeration  factor  of  the  values  in  the  elevation  file. 

Default:  3 

If =4ine ^frequency  Contour  intervals  at  which  vector  grid  lines  will  be  drawn,  in  meters. 

Default:  20 

back  =background-Coior 

Color  erf  the  background  of  the  display  frames. 

Options:  red,  orange,  yellow,  green,  Hue,  indigo,  violet,  magenta,  brown,  gray, 
white,  and  black 
Default:  black 

NOTES 

In  the  spearfish  sample  data  base,  the  user  must  specify  a  viewing  height  when  running  3d.view.sh. 
Note  also  that  the  raster  elevation  map  layers  in  the  PERMANENT  mapset  under  spearfish  are  named 
elevation.dem  and  elevation.dma. 

Iliis  program  will  not  prompt  the  user  for  inputs;  if  the  user  types  3d. view  .sh  without  program 
arguments  on  the  command  line,  default  values  will  be  used. 

FILES 

This  program  is  simply  a  shell  script.  Users  ;ire  encouraged  to  make  their  own  shell  scripts  using 
similar  techniques.  Sec  $GISBASE/scripts/3d.vicw.sh. 
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SEE  ALSO 

d.3d,  cLrast 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

GenMaps  -  Generates  various  vector  maps  from  a  rim/EIGER  data  base. 

(GRASS  Shell  Script) 

SYNOPSIS 

Gen.Maps  help 

Gen. Maps  dbname  tractNl  tractN2  ... 

DESCRIPTION 

Gen.Maps  is  a  shell  script  that  queries  information  from  a  rim  data  base  using  the  GRASS  command 
v.db.rim,  which  is  an  interface  between  GRASS  and  RIM.  The  dbname  given  on  the  command  line 
should  be  the  name  of  a  rim  data  base  created  using  v.in.tiger.  Gen.Maps  will  create  several  new 
vector  files.  'I Tree  of  these  are:  a  county  outline  map,  a  map  of  tract  boundaries  within  the  county ,  and 
a  map  showing  Mock  group  boundaries.  For  every  tract  number  given  on  the  input  line,  additional 
vector  maps  will  be  created  showing:  the  tract  outline,  a  block  group  boundary  map  for  each  block 
group  within  the  tract,  and  a  map  showing  block  boundaries  within  each  block  group.  Output  files  will 
be  named  dbname  .county ,  dbname. tract  and  dbname.bg  for  the  map  layers  showing  the  county 
outline,  the  tract  outlines  within  the  county,  and  the  block  group  boundaries  within  the  county.  The 
vector  file  showing  the  boundary  for  an  individual  tract  will  be  named  1 tractN,  where  tractN  is  the 
tract  number  given  on  the  command  line.  The  vector  files  created  to  show  an  individual  block  group 
boundary  and  block  boundaries  within  that  block  group  will  be  named  using  the  appropriate  tract 
number  and  block  group  number  as  part  of  die  name,  with  suffixes  of  bg  and  .bk  respectively. 

Parameters: 

dbname  Name  of  an  existing  rim  data  base. 

tractN  Number  of  a  tract  located  within  this  county. 

NOTES 

'Iliis  command  must  be  installed  separately  as  part  of  the  package  of  routines  dealing  with  the  import  of 
Census  (TIGER)  data.  It  requires  the  use  of  rim  and  v.db.rim,  which  must  be  compiled  first. 

Y<xi  must  include  at  least  one  tract  number  on  the  command  line  for  this  command  to  function.  Us< 
tiger. info ~sh  to  obtain  all  tract  numbers  for  a  given  TIGER  typel  data  file. 

If  the  master  binary  vector  file  created  using  v.in.tiger  is  modified  after  it  is  in  GRASS,  this  program 
will  probably  not  work.  In  that  situation,  the  processes  from  this  shell  script  may  simply  be  run  by 
hind,  using  v.db.rim  directly,  but  searching  the  old  veciur  file  to  find  lines  for  the  new  vector  files 
without  using  the  Unary  offset  field  (vectoff). 

Vector  files  showing  the  block  boundaries  within  a  block  group  may  contain  hydrology  lines,  which  in 
fact  define  the  edge  of  a  census  block. 

SEE  ALSO 

v.in.tiger,  v.db.rim,  GenJractmap,  tiger. info.sh 

AUTHOR 

James  Ffinthomc  ;utd  David  Satnik,  GIS  I^ab,  Central  Washington  University.  Elensburg,  WA. 
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NAME 

GenJractmap  -  Generates  two  vector  maps  from  a  RIM/TIGER  data  base. 

(GRASS  Shell  Script) 

SYNOPSIS 

Gen.traetmap  help 
Gen.traetmap  dbname 

DESCRIPTION 

Gen.traetmap  is  a  shell  script  which  queries  information  from  a  RIM  data  base  using  the  GRASS 
command  v.db.rim,  which  is  an  interface  between  GRASS  and  RIM.  Ihe  dbname  given  on  the 
command  line  should  be  the  name  of  a  RIM  database  created  using  v. in. tiger.  Gen.traetmap  will 
create  two  new  vector  files:  one  showing  the  county  outline  and  one  showing  all  tract  boundaries  within 
the  county.  These  output  files  will  be  named  dbname  .county  and  dbname  .tract ,  respectively. 

Parameters: 

dbname  Name  of  an  existing  RIM  data  base. 

NOTES 

This  command  must  be  installed  separately  as  part  of  the  package  of  routines  dealing  with  the  import  of 
Census  (TIGER)  data.  It  requires  the  use  of  rim  and  v.db.rim,  which  must  be  compiled  first. 

The  output  maps  produced  by  this  command  are  also  included  as  part  of  the  more  extensive  output 
from  Gen. Maps 

If  the  master  binary  vector  file  created  using  v.inJiger  is  modified  after  it  is  in  GRASS,  this  program 
will  probably  not  work.  In  that  situation,  the  processes  from  tins  shell  script  may  simply  be  run  by 
hand,  using  v.db.rim  directly,  but  searching  the  old  vector  file  to  find  lines  for  the  new  vector  files 
without  using  the  binary  offset  field  (vectoff). 

SEE  ALSO 

v.in.tiger,  v.db.rim,  Gen.Maps,  tigerJnfojh 

AUTHOR 

James  lEnthome  and  David  Salnik.  GIS  Lab,  Central  Washington  University,  Illensburg,  WA. 
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NAME 

blendsh  -  Combines  the  red,  green,  and  blue  color  components  of  two  raster  map  layers. 

(GRASS  Shell  Script) 

SYNOPSIS 

blend.sh  filel  file2  perc  outbade 
DESCRIPTION 

blendjh  is  a  Bourne  shell  (sh(l ))  script  that  extracts  the  red  (R),  green  (G).  air1  blue  (B)  color 
components  from  each  of  two  raster  map  layers,  and  creates  three  new  raster  map  layers  whose 
category  values  respectively  represent  the  combined  red,  combined  blue,  and  combined  green  color 
values  from  the  two  input  layers.  Category  values  in  each  of  the  output  map  layers  will  fall  within  the 
range  of  0  -  255 . 

Ihe  R.G.B  values  from  the  two  input  map  layers  (/i/e 7  and  file2)  are  not  simply  added  together,  but  are 
instead  combined  by  a  user- named  percentage  (perc )  of  the  R,C i,B  values  in  filel.  Specifically, 
blemish  executes  three  r.mapcalc  statements  that:  (1)  convert  the  R,G3  values  in  filel  and  file2  to 
the  range  0  -  255;  (2)  multiply  the  R,  Ci,  and  B  values  in  filel  by  a  user-named  percentage  (perc)',  (3) 
multiply  the  R,  G,  and  B  values  in  file2  b\  (1(H)  perc );  (4)  create  three  new  raster  map  layers,  whose 
categorv  values  represent  the  summed  R,  summed  G,  or  summed  B  values  resulting  from  (2)  and  (3). 
Resulting  R,  G,  and  B  values  will  respectively  be  stored  in  three  new  raster  map  layers  named 
(fut  base,  r,  out  base. g  and  out  base.  b. 

Ihis  program  runs  non-interactively;  the  user  must  state  all  parameter  values  on  the  command  line. 


Parameters: 

file  1 

file2 


perc 
out  haw 


Name  of  a  first  raster  map  layer,  whose  R  G,  and  B  color  components  will  be 
combined  with  those  of  the  second  raster  map  layer  (file2 )  named.  Ihe  percent 
value  (perc )  given  will  apply  to  filel. 

Name  of  a  second  raster  map  layer,  whose  color  components  will  be  combined 
with  those  of  filel.  Ihe  percent  value  (perc)  given  will  apply  to  the  R,G,P 
values  in  filel.  The  R,  G,  and  B  values  in  file 2  will  be  multiplied  by  (100 
perc)  7<>. 

Percentage  or  amount  of  the  color  contribution  in  terms  of  color  intensity.  Ihis 
value  is  multiplied  by  the  RGJb  values  in  filel. 

Ihe  root  name  assigned  to  each  of  the  three  output  files  created.  A  suffix  is 
added  to  each  file  name,  indicating  which  hold  the  red,  green,  and  blue  color 
values. 


blendjh  executes  three  r.mapcalc  statements: 

r.ma|xralc  "outbase. r  =  rflfUel  *  perc  +  (1.0  -  perc)  *  r#file2" 
r.mapcalc  "outbase  g  =  gfifilel  *  perc  +  (1.0  perc)  *  g#fde2” 
r.mapcalc  "out base. b  =  b IfUel  *  perc  +  (1.0  perc)  *  b#(Ue2" 

It  uses  the  #  operator  to  separately  extract  the  red,  green,  and  blue  components  in  the  named  raster  map 
layers,  essentially  allowing  color  separates  to  be  made. 

EXAMPLE 

Typing  the  following  at  the  command  line: 

blend.sh  aspect  elevation  40  elev^isp 

will  create  three  new  raster  map  layers  named  elev.asp.r.  elev.aspp.  ;uid  elev.asp.b ,  that,  respectively, 
contain  40  of  the  red.  green,  and  blue  com|mncnts  of  the  elevation  map  layer  and  contain  60  of  the 
red.  green.  ;uul  blue  components  of  lire  aspect  map  layer. 
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FILES 

This  program  is  simply  a  shell  script.  Users  are  encouraged  to  make  their  own  shell  scripts  using 
similar  techniques.  See  SGJSBASE/scripts/Wend^h. 

SEE  ALSO 

r. colors,  rjnapcalc 

AUTHOR 

David  Gerdes,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

bug.reportJh  -  A  mechanism  for  writing,  storing,  and  e-mailing  to  USACERL  users’  bug  reports  on 
GRASS  4.0  commands. 

(GRASS  Shell  Script) 

SYNOPSIS 

bug.report.sh  4.0_programjuunc  [programjarguments ] 

DESCRIPTION 

bug.reportJh  is  a  Bourne  shell  (sh(l))  script  that,  when  given  a  GRASS  4.0  program  name,  allows  the 
user  to  complete  a  bug  report  for  that  program.  Completed  bug  reports  can  be  e-mailed  to  the  GRASS 
development  group  at  USACERL,  saved  to  a  file  in  the  user’s  home  directory,  or  discarded. 

This  program  is  not  interactive;  the  user  must  specify  the  name  of  a  4.0  program  on  the  command  line. 
Program  arguments  can  optionally  be  entered  by  the  user. 

Parameters: 

4.0  progranuname  The  name  erf  an  existing  GRASS  version  4 .0  program  tested  by  the  user. 
program^argument(s) 

Program  arguments  (parameters  anchor  flags)  for  the  4.0  programjiame  tested  by 
the  user.  The  user  should  enter  whatever  command  arguments  were  actually  run 
when  the  program  bug  occurred. 

EXAMPLE 

For  example,  if  the  user  wished  to  complete  a  bug  report  on  v.to.rast  after  running  the  program,  the 
user  might  then  type: 

bug.report.sh  Tiariist 

A  standard  bug  report  form  would  then  be  displayed  on  the  user’s  text  terminal,  containing  the  user’s 
current  GRASS  region  settings,  and  the  machine  name,  GRASS  data  base,  location,  and  mapset,  on 
which  the  user  is  currently  running  GRASS.  Program  parameters  and  flag  settings,  and  the  command 
enteral  by  the  user  on  the  command  line,  are  also  automatically  entered  on  the  bug  report  form.  Th< 
user  is  [Hit  into  a  text  editor  and  expected  to  enter  additional  information  describing  the  nature  of  the 
Ixig  found  or  the  results  of  program  testing. 

Ihe  user  is  then  asked  whether  the  completed  bug  report  is  to  be: 

1  mailed  to  westerve@zorro.cecer.army  mil 

2  -  added  to  the  file  "grass.bugs"  in  the  user’s  home  directory 

3  both  1  and  2 

4  thrown  away 

NOTES 

Ibis  program  prints  whatever  region  settings,  GRASS  data  base,  fixation,  arxl  mapset  are  current  when 
the  user  nuts  bug. report. sh.  lire  user  is  therefore  advised  to  nut  bug.report.sh  immediately  after 
ex|xricncing  a  program  bug,  to  ensure  that  the  settings  current  when  the  bitg  occurred  arc  re|»rted  on 
the  Urg  report  form. 

FILES 

Ibis  shell  script  is  stored  tuidcr  the  SGISB ASF/scripts  directory  on  the  user’s  system.  'Ihe  user  is 
encouraged  to  examine  die  shell  script  commands  stored  in  this  directory  and  to  produce  similar  scripts 
for  then  own  use.  I  sers  might  modify  this  shell  script  to  e-mail  reports  of  program  Uigs  to  a  local 
systems'  administrator  in  addition  to  someone  at  USACERL. 

AUTHOR 

l.unes  \Vcslcrvell .  I  S  Amn  Construction  Engineering  Research  laboratory 
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NAME 

dcorrelatejh  —  Graphically  displays  the  correlation  raster  map  layers  in  the  active  frame  on  the 
graphics  monitor. 

(GRASS  Shell  Script) 

SYNOPSIS 

dcorrelate^h  layer  1  layer2  [layer 3  [layer4}\ 

DESCRIPTION 

dcorrelate .sh  is  a  C-shell  (csh(l))  script  that  graphically  displays  die  results  of  an  ratals  run  on  two 
raster  map  layers.  This  shell  script  is  useful  for  highlighting  the  correlation  (or  lack  of  it)  among  data 
layers. 

Ihe  results  are  displayed  in  the  active  display  frame  on  the  user’s  graphics  monitor,  dcorrelate.. sh 
erases  the  active  frame  before  displaying  results. 

Parameters: 

layerl  layer2  [layer3  [layer 4}] 

Ihe  names  of  from  two  to  four  existing  raster  map  layers  to  be  included  in  the 
correlation. 

NOTES 

Ihis  is  a  shell  script  that  uses  r  j tats  and  the  UNIX  awk  command  to  calculate  the  correlation  among 
data  layers,  and  uses  d.text  and  (Lgraph  to  display  the  results. 

If  three  or  four  map  layers  are  specified,  the  conelation  among  each  combination  of  two  data  layers  is 
displayed. 

Ihis  command  is  written  for  /bin/csh.  If  your  system  doesn’t  support  this  shell,  don’t  install  this  script. 

FILES 

This  program  is  simply  a  shell  script.  Users  are  encouraged  to  make  their  own  shell  script  programs 
using  similar  techniques.  See  SdSBASE/scripts/dconelate.sh. 

SEE  ALSO 

The  UNIX  awk  command 
d.text,  d.graph,  r.coin,  r. stats 

AUTHOR 

Michael  Shapiro,  U  S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

grass.logojh  -  Displays  a  GRASS/ Army  Corps  of  Engineers  logo  in  the  active  display  frame  on  the 
graphics  monitor. 

(GRASS  Shell  Script) 

SYNOPSIS 

grass.logojh 

DESCRIPTION 

grass.logo.sh  is  primarily  a  demonstration  of  the  GRASS  d.graph  program  in  a  UNIX  Bourne  shell 
macro  that  generates  the  U.S.  Army  Corps  of  Engineers  logo.  Users  are  encouraged  to  generate  their 
own  unique  logos  by  writing  similar  macro  shell  scripts.  Examine  the  contents  erf  the  input  file  called 
grass.logo.sh  located  in  the  GRASS  shell  script  command  directory  ( SGISBAS E/scripts )  to  see  how 
the  GRASS  logo  was  generated  using  d.graph  graphics  commands.  The  coordinates  for  this  logo  were 
taken  from  a  drawing  done  on  graph  paper. 

To  view  the  graphics  described  by  this  file  use  digraph  or  dmapgraph,  making  sure  that  a  copy  of  this 
file  is  either  in  your  current  directory  or  is  given  by  its  full  path  name. 

NOTES 

grass. logo.sh,  like  d.rast,  will  overwrite  (not  overlay)  whatever  display  appears  in  the  active  graphics 
frame. 

This  program  requires  no  command  line  arguments. 

SEE  ALSO 

d.font,  d.graph,  d.mapgraph,  d.rast 
AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

hsvjgb.sh  -  Converts  KSV  (hue,  saturation,  and  value)  cell  values  to  RGB  (red,  green,  and  blue) 
values. 

(GRASS  Shell  Script) 

SYNOPSIS 

hsr.rgb.sh  filel  file2  file3 

DESCRIPTION 

hsv.rgb.sh  is  a  Bourne  shell  (sh(l))  program  that  converts  HSV  to  RGB  using  r.mapcalc.  The  Foley 
and  Van  Dam  algorithm  is  the  basis  for  this  program.  Input  must  be  three  raster  files  -  each  file 
supplying  the  HSV  values.  Three  new  raster  files  are  created  representing  RGB. 

NOTES 

Do  not  use  tl»e  same  names  for  input  and  output. 

FILES 

This  program  is  simply  a  shell  script  stored  in  the  file  hsv.rgb^h  under  the  $GISBASE/scripts 
directory.  Users  are  encouraged  to  make  their  own  shell  script  programs  using  similar  techniques. 

SEE  ALSO 

rgbJisv.sh 

AUTHOR 

Tames  Westervelt,  U.S.  Army  Coonstruction  Engineering  Research  Laboratory 
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NAMK 

old.cmdxh  -  Provides  the  new  GRASS  version  4.0  program  name  for  any  program  name  in  GRASS 
version  3.2. 

(GRASS  Shell  Script) 

SYNOPSIS 

oidxmd.sh  3.2 __program.name 
DESCRIPTION 

old.cmdjh  is  a  Bourne  shell  (sh(l))  script  that,  when  given  a  GRASS  3.2  program  name,  returns  the 
name  of  the  new  GRASS  version  4.0  program  performing  its  functions,  This  program  is  useful  as  a 
quick  on-line  cross-reference  between  GRASS  versions  3  and  4.  This  program  is  not  interactive;  the 
user  must  specify  the  name  of  a  32  program  on  the  command  line. 

Parameter: 

3.2 ^program.name  The  name  of  an  dd  GRASS  version  32  program. 

Output  will  be  in  the  form: 

old  3.2  program  name  replaced  with:  new  4.0  program  name 

EXAMPLE 

For  example,  to  learn  which  GRASS  4.0  command  performs  the  function  of  the  GRASS  32  list 
command,  th  user  might  type: 

oid.cmd-sh  list 

Ihe  user  would  then  see  the  following  message  displayed  to  standard  output: 
list  replaced  with:  g.list 

FILES 

Ihis  shell  script  is  stored  under  the  SGISBASB'scripts  directory  on  the  users  system.  Ihe  user  is 
encouraged  to  examine  the  shell  script  commands  stored  in  this  directory  and  to  produce  similar  scripts 
for  their  own  use. 

AUTHOR 

James  Wcstcrvelt,  U.S.  Army  Qmstmction  Engineering  Research  laboratory 
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NAME 

rgbJisv.sh  -  Converts  RGB  (red,  green,  and  blue)  cell  values  to  HSV  (hue,  saturation,  and  value) 
values. 

(GRASS  Shell  Script) 

SYNOPSIS 

rgbJisv.sh  filel  file2  file3 

DESCRIPTION 

rgbJisv.sh  is  a  Bourne  shell  (sh(l))  program  that  converts  RGB  values  to  HSV  using  rjmapcalc.  The 
Foley  and  Van  Dam  algorithm  is  die  basis  for  the  program.  Input  must  be  three  raster  liles  -  each  file 
supplying  the  RGB  values.  Three  new  raster  files  are  created  representing  HSV. 

NOTES 

Eto  not  use  the  same  names  for  input  and  output. 

FILES 

Hus  program  is  simply  a  shell  script  stored  under  the  SGlSBASlVscripts  directory.  The  user  is 
encouraged  to  examine  the  shell  script  programs  stored  here  and  to  produce  other  such  programs. 

SEE  ALSO 

hsv.rgb.sh 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

shade. r  el  sh  -  Creates  a  shaded  relief  map  based  on  current  resolution  settings  and  sun  altitude  and 
azimuth  values  entered  by  tlte  user. 

(GRASS  Shell  Script) 

SYNOPSIS 

shade.rel.sh 

DESCRIPTION 

shade. r el  Jih  is  a  Bourne  shell  (sh(l))  script  that  creates  a  raster  shaded  relief  map  based  on  current 
resolution  settings  and  on  sun  altitude  and  azimuth  values  entered  by  the  user.  The  new  shaded  relief 
map  is  named  shade  and  stored  in  the  user’s  current  mapset.  The  map  is  assigned  a  grey  scale  color 
table. 

This  program  is  interactive;  the  user  enters  the  command: 

shikde.reCsh 

The  program  then  prompts  the  user  to  enter  values  lor. 

(1)  the  altitude  of  the  sun  in  degrees  above  the  horizon  (a  value  between  0  and  90  degrees), 

(2)  the  azimuth  of  the  sun  in  degrees  to  the  east  of  north  (a  value  between  -1  and  360 
degrees),  and 

(3)  the  name  of  a  raster  map  layer  whose  cell  category  values  are  to  provide  elevation  values 
for  the  shaded  relief  map.  Typically,  this  would  be  a  map  layer  of  elevation;  however,  any 
raster  map  layer  can  be  named. 

Specifically,  shade.rel.sh  executes  the  following  r.mapcalc  statement: 

r.mapcalc  «BOT' 
shade  =  eval(  \ 

x=($elev[ - 1 1  ]  +  2*$elev[0,-l]  +  $elev(l,-l]  \ 

-Selev[- 1,1]  -  2*SelevjO,l)  -  $elev(l,l])/(8.*$ewres)  ,\ 
v=(Selev[-l ,1]  +  2*Sclev[-l,0]  +$elev[-l,l]  \ 

-Selcv[l,-1]  -  2»Selev[l,0]  -  $elcv[l,l])/(8.*$nsres)  ,\ 
slope=90.-atan(sqrt(x*x  +  y*y)),  \ 
a=r<xind(at;ui(x,y)),  \ 
aspect =if(x  |jy,if(a.a360)),  \ 

cang  =  sin(Salt)*sin(slope)  +  cos(Salt)*cos(slope)  *  cos(Saz-aspect),  \ 
if(c;uig  <0.(),100*cang)) 

FDf- 

Refer  to  the  manual  entry  fix  r.mapcalc  for  an  explanation  of  the  filtering  syntax  shown  in  the  above 
expression.  See,  for  example,  the  section  on  "The  Neighborhood  Modifier." 

shade.rel.sh  then  nms  r.colors  to  assign  a  grey  scale  color  table  to  the  new  shaded  relief  map  shade , 
by  executing  the  command: 

r.colors  shude  color  ^rey 

FILES 

This  prog  nun  is  simply  a  shell  script.  Users  ;ire  encouraged  to  make  their  own  shell  scripts  using 
similar  techniques.  See  SGISBASI;/scripts/shade.rel.sh. 

SEE  ALSO 

” r.mapcalc :  Ail  Algelxa  for  (IIS  and  Image  Processing,”  by  Michael  Shapiro  and  James  Westcrvelt, 
U  S  Arm\  Construction  Engineering  Research  laboratory  (March  1991). 

"GRASS  T  utorial:  r.mapcalc."  by  Marjorie  I  .arson,  U  S.  Army  Constniction  Engineering  Research 
1  alxiratorv. 
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blendjh,  g.ask,  g.region,  r. colors,  and  r.mapcalc 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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NAME 

show. color  jh  -  Displays  and  names  available  primary  colors  used  by  GRASS  programs,  in  frames  on 
the  graphics  monitor. 

(GRASS  Shell  Script) 

SYNOPSIS 

showxoior^h 

DESCRIPTION 

show.color^h  is  a  UNDC  Bourne  shell  macro  that  displays  and  names  available  primary  colors  used  by 
GRASS  programs  in  frames  on  the  graphics  monitor.  Available  colors  are:  red,  orange,  yellow, 
green,  blue,  indigo,  violet,  white,  black,  gray,  brown,  magenta,  and  aqua. 

No  program  arguments  are  required  to  nin  this  program. 

NOTES 

The  full  monitor  screen  is  made  the  active  frame  after  this  program  ends. 

Ibis  macro  is  located  in  $GlSBASEJscripts/show. color. sh. 

SEE  ALSO 

d.colormode,  d.colors,  d.colortable,  d.display,  d.frame,  grass.logojh,  show.fonts.sh 

AUTHOR 

David  Gerdes,  U.S.  Army  G instruction  Tngineering  Research  laboratory 
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NAME 

show.fontsjh  -  Displays  and  names  available  font  types  in  the  active  display  frame  on  the  graphics 
monitor. 

(GRASS  Shell  Script) 

SYNOPSIS 

showr.fonts.sh 

DESCRIPTION 

show. font SJih  is  a  UNIX  Bourne  shell  macro  that  runs  the  d.erase  -a  command,  then  names  and 
displays  the  font  types  that  can  be  selected  using  d.font.  This  macro  also  runs  the  GRASS  commands 
d.font  and  dJext.  See  the  manual  entry  for  d.font  for  instructions  on  choosing  a  font  type. 

No  program  arguments  are  required  to  ntn  this  program. 

BUGS 

The  font  is  set  to  romans  (Roman  simplex)  after  running  show.fontssh.  There  is  no  mechanism  to 
query  the  current  font,  so  there  is  no  way  to  automatically  restore  the  font.  The  user  will  have  to  reset 
the  font  type  using  d.font  if  romans  is  not  desired. 

FILES 

This  program  is  simply  a  shell  script  stored  under  the  SGISBASE/scripts  directory  .  Users  are 
encouraged  to  examine  the  shell  script  programs  stored  here  and  to  produce  others  for  their  own  use. 

SEE  ALSO 

d.display,  <Lerase,  d.font,  grass. logosh,  dJabel,  tLlegend,  d.paint. labels,  d.text,  d.title 

AUTHOR 

James  Westervelt,  U.S.  Army  Construction  Engineering  Research  laboratory 
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NAME 

slide  show  sh  -  Displays  a  series  of  raster  map  layers  existing  in  the  user’s  current  mapset  search  path 
on  the  graphics  monitor. 

(GRASS  Shell  Script) 

SYNOPSIS 

slide. shcw^h  [ across  =vo/uej  [down  =value]  [mapsets=/ijf] 

DESCRIPTION 

slideshow  sh  is  a  UNIX  Bourne  shell  macro  that  clears  the  entire  screen,  creates  a  series  of  display 
frames  on  the  graphics  monitor,  and  displays  in  slideshow  format  each  of  the  raster  map  layers  listed  in 
the  user- specified  mapset s.  This  is  a  shell  script  example  that  makes  extorsive  use  of  GRASS  and 
UNIX  commands.  Users  are  encouraged  to  examine  tins  macro  and  develop  similar  on-line  demos 
using  their  own  data  files. 

Parameters: 

across  =va/ue  The  number  of  display  frames  across  the  graphics  monitor  screen  to  be  used  for 

map  display. 

Default:  4 

down  value  The  number  of  display  frames  down  the  graphics  monitor  screen  to  be  used  for 

map  display. 

Default:  3 

mapsets  list  The  names  of  the  mapsets  under  the  user’s  current  location  whose  raster  map 

layers  are  to  be  displayed,  separated  by  commas. 

Default:  All  mapsets  listed  in  the  user’s  current  mapset  search  path. 

FILES 

See  the  file  slide.show.sh  under  SGISBASE/scripts. 

SEE  ALSO 

d.display,  (Lerase,  d.text,  g  mapsets,  3d.view.sh,  demosh,  grass.logo.sh,  show. fonts  sh 
AUTHOR 

Janies  Wcstcrvclt,  U.S.  Army  Constmction  Engineering  Research  Laboratory 
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NAME 

split  jsh  -  Divides  the  graphics  monitor  into  two  frames  and  then  displays  two  maps  in  these  frames. 
(GRASS  Display  Program) 

SYNOPSIS 

split.sh  mapoame  mapname  [cmd  ( lRASS_command\  [cmd2  GRASS_convnand\  [ view  =he  ■  - 
DESCRIPTION 

split jh  is  a  Bourne  shell  (sh(l))  script  that  clears  the  entiie  graphics  screen  and  divides  it  into  two 
display  frames.  Map  layers  are  then  displayed  in  each  of  the  two  frames.  This  command  is  very  useful 
for  visually  comparing  maps  (raster,  vector,  and  3-d  views)  and  can  be  used  by  other  GRASS  shell 
macros.  It  is  also  useful  for  creating  demos.  Program  parameters  are  given  below. 

Parameters: 

view=horiz  'Ihe  graphics  screen  can  be  split  either  horizontally  or  vertically.  The  default 

view  splits  the  screen  into  two  frames,  one  tat  the  left  and  one  on  the  right  (a 
vertical  split).  Some  maps  (  3-d  views)  are  better  represented  with  more  width 
then  height  (horizontal  split).  The  first  map  name  listed  on  the  command  line  will 
be  displayed  in  the  top  or  left  window  (depending  on  whether  the  screen  was  split 
horizontally  or  vertically),  and  the  second  map  will  be  displayed  in  the  bottom  or 
right  window. 

cmd  GRASS  ^command 

The  GRASS  command  used  to  display  the  named  mapnames.  If  no  command  is 
specified  by  the  user,  tLrast  is  used  by  default.  However,  any  GRASS  display 
command  (e.g.,  d.3d,  cLvect,  etc...)  can  be  entered. 

cmd2  GRASS  command 

This  command  will  be  used  to  display  map  data  in  the  second  frame  only 

If  tlie  user  fails  to  specify  the  values  of  both  cmd  and  cmd2fR,  split  jh  will  use 
the  default  command  ( d.rast )  to  display  user  specified  map  layer  names  in  both 
frames.  If  the  user  specifies  only  the  value  of  cmd  on  the  command  line,  then 
that  command  will  be  executed  for  both  frames.  If  the  user  specifies  the  values  of 
Ixrth  cmd  and  cmd2  on  the  command  line,  the  cmd  command  will  lie  executed  in 
frame  1  and  the  cmd2  command  will  lx-  executed  in  frame  2. 

EXAMPLES 

split.sh  soils  vegcover 

split.sh  soils  cmd2  dJegend  "soils  red" 

split.sh  elevation  vegcover  cmd  d3d  view  horiz 

NOTES 

split  jh  leaves  the  fr;uuc  that  the  last  map  was  drawn  in  as  the  active  frame.  Ihe  order  in  which  the 
options  (cmd,  cmd2,  view)  are  placed  on  the  comnumd  line,  doesn't  matter.  Wit  the  order  is  important 
for  the  map  names. 

FILES 

Ihis  prog  nun  is  simply  a  si  tell  script.  Users  are  encouraged  to  make  their  own  shell  scripts  using 
similar  techniques.  See  SGISB AS1  /scnpts/split.sh. 

SEE  ALSO 

d.3d,  d./rame,  d.rast,  d.sites,  d.vect 

AUTHOR 

Michael  Higgins,  U  S.  Army  Construction  Engineering  Research  Ialxiratorv 
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NAME 

start jnanjh  -  Creates  the  template  for  a  manual  entry  in  standard  User’s  Reference  Manual  format  for 
a  user-specified  GRASS  4.0  command. 

( GRASS  Shell  Script) 

SYNOPSIS 

start.man.sh  4.0 _programjiame 
DESCRIPTION 

start jnanjsh  is  a  Bourne  shell  (sh(l))  script  that,  when  given  a  GRASS  4.0  program  name,  creates  a 
basic  manual  entry  for  that  program  in  the  same  standard  format  as  that  used  by  die  GRASS  User's 
Reference  Manual.  The  named  program  must  already  exist  under  a  directory  for  GRASS  main,  alpha, 
or  contributed  source  code. 

This  program  is  not  interactive;  the  user  must  specify  the  name  of  a  4.0  program  on  the  command  line. 

By  default,  program  output  will  be  sent  to  standard  output  (i.e.,  displayed  to  the  user’s  text  terminal). 
If  the  user  wishes  to  save  the  manual  entry  created  by  start  jnanjsh,  program  output  can  be  redirected 
into  a  file.  For  example,  the  below  command  will  create  a  manual  entry  for  the  program  newjrrogram, 
and  save  output  to  the  file  new.progranunan  in  the  user’s  current  directory. 

start  .m  an  .sh  new  .program  >  new  .program  .man 

Parameter: 

4 . O^progranuname  The  name  of  an  existing  GRASS  program  located  in  a  source  code  directory  for 
main,  alpha,  or  contributed  software. 

FILES 

This  shell  script  is  stored  under  the  SdSBASE/scripts  directory  on  the  user’s  system.  The  user  is 
encouraged  to  examine  the  shell  script  commands  stored  in  this  directory  and  to  produce  similar  scripts 
for  their  own  use. 

SEE  ALSO 

GRASS  4.0  User’s  Reference  Manual,  by  James  Westervelt,  Michael  Shapiro,  et  al.  (USACERL). 
bug.reporuh,  gJielp,  g. manual 
AUTHOR 

James  Westervelt,  US.  Army  Construction  Engineering  Research  laboratory 
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NAME 

tiger Jnfojh  -  Provides  tract  numbers)  and  classification  codes  found  within  a  given  U.S.  Census 
Bureau  TIGER  typel  data  file. 

(GRASS  Shell  Script) 

SYNOPSIS 

tiger  Jnfo^h  help 
tiger  Jnfo^h  infile 

DESCRIPTION 

tiger. inf o^h  is  a  shell  script  that  outputs  tract  numbers)  and  classification  codes  found  within  the 
TIGER  typel  data  file  infile.  Output  is  written  to  standard  out,  and  can  be  captured  in  a  file  by 
redirecting  output.  This  information  is  useful  when  querying  (using  v.db.rim )  from  the  master  binary’ 
vector  file  created  by  vJn.tiger.  It  also  prov  ides  tract  numbers)  that  can  be  used  as  input  to  the 
command  Gen. Maps. 

Parameters: 

infile  Name  of  a  TIGER  typel  data  file. 

NOTES 

This  command  must  be  installed  separately  as  part  of  the  package  of  routines  dealing  with  the  import  of 
Census  (TIGER)  data. 

SEE  ALSO 

nuiger. region,  vjnJiger,  v.db.rim,  Gen. Maps,  Gen.tractmap 

AUTHOR 

Marjorie  Larson,  U.S.  Army  Construction  Engineering  Research  Laboratory 
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CONTRIBUTED  PROGRAMS 


This  chapter  describes  code,  primarily  contributed  by  other  user  sites,  that  has  undergone  only  limited 
internal  testing  and  has  not  yet  been  beta-tested.  These  programs  appear  in  the  src.contrib  directory  and 
are  not  compiled  during  general  GRASS  compilation;  users  must  compile  these  programs  separately  to 
run  them.  Be  advised  that  these  programs  may  not  work  as  expected. 

Other  software  also  distributed  with  GRASS  is  not  documented  in  this  volume;  this  includes  programs 
contained  under  the  src. garden  and  sre.related  directories  that  the  user  must  compile  separately  (see  the 
GRASS  Installation  Guide  for  compilation  instructions).  The  sre.garden  directory  includes  program 
interfaces  that  link  GRASS  4.0  with  other  related  software  (including  UW-RIM  and  BNOISE).  The 
sre.related  directory  includes  programs  to  which  GRASS  has  been  interfaced  that  program  developers  have 
allowed  to  be  distributed  with  GRASS  (such  as  UW-RIM  and  BNOISE,  MAPGEN,  GCTP,  PBMPLUS, 
and  XGEN).  These  programs  are  described  in  their  original  program  documentation. 
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NAME 

DOS.delete  -  SCS  DOS  P06300  display  station  image  support. 

(SCS  GRASS  Graphics  File  Management  Program) 

(Available  for  PC6300  workstations,  only) 

SYNOPSIS 

DOS.delete 
DOS.delete  help 

DESCRIPTION 

'Ihis  command  allows  a  user  to  interactively  remove  PC6300  saved  images  from  the  MS-DOS  disk. 
lX)Sjsave  will  store  an  image  produced  by  cLdisplay,  d.rast,  etc.  on  the  PG6300  display  from  the 
6300  hard  disk. 

NOTES 


Ihis  program  only  works  with  PC6300  workstations. 
SEE  ALSO 

DOSJist,  DOSsave,  DOSshow 

AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHQ-CGIS 
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NAME 

DOSJist  -  Lists  stored  screen  images  residing  on  the  F06300  MS-DOS  hard  disk. 

(SCS  GRASS  Graphics  File  Management  Program) 

(Available  for  PC6300  workstations,  only) 

SYNOPSIS 

DOSJist 
DOSJist  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively  list  PG63O0  screen  images  that  were  saved  using  DOSjave, 
on  the  PG6300  hard  disk.  DOSJist  will  find  MS-DOS  files  with  the  extension  "  .GRS"  in  the  current 
DOS  directory. 

NOTES 

This  program  is  for  use  with  PG6300  workstations,  only. 

SEE  ALSO 

DOS.delete,  DOS.save,  DOSjhow 


AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHQ-CGIS 
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NAME 

DOSjave  -  Stores  screen  images  to  the  P06300  MS-DOS  hard  disk. 

(SCS  GRASS  Graphics  File  Management  Program) 

(Available  for  PC6300  workstations,  only) 

SYNOPSIS 

DOS.save 
DOS. save  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively  save  PG6300  screen  images  produced  by  GRASS  graphics 
display  programs  (like  d.display,  d.rast,  etc.)  to  the  PG6300  hard  disk.  It  will  assign  the  extension 
".GRS"  to  the  filename  given,  and  will  store  the  image  file  in  the  user's  current  DOS  directory .  The 
files  are  binary  image  files,  representing  the  red,  green,  and  Hue  planes  of  the  DEB  board  graphic 
memory. 

NOTES 

This  program  is  for  use  with  PG6300  workstations,  only. 

SEE  ALSO 

DOS.delete,  DOS.list,  lX)S.show 

AUTHOR 

P.  W.  Carison,  USDA  SCS,  NH>OGIS 
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NAME 

DOSjhow  -  Reads  screen  images  stored  on  the  P06300  MS-DOS  hard  disk  by  DOSjave. 

(SCS  GRASS  Display  Program) 

(Available  for  PC6300  workstations,  only) 

SYNOPSIS 

DOS-show 
DOS.show  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively  view  PC6300  screen  images  produced  by  d.display,  d.rast, 
etc.  and  saved  to  the  PC630O  hard  disk  by  DOSjave. 

NOTES 

This  program  is  for  use  with  PC6300  workst-tions,  only. 

SEE  ALSO 

DOS.delete,  DOSJist,  DOSjave 

AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHOOG1S 
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NAME 

d.6386.delete  -  Deletes  images  from  a  F06386  workstation  hard  disk,  that  were  created  by 
d.6386 jave. 

( SCS  GRASS  Graphics  File  Management  Program) 

(Available  for  PC6386  UNIX  workstations,  only) 

SYNOPSIS 

d.6386.delete 
d.6386.delete  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively  remove  PG6386  saved  images  from  the  hard  disk. 
d.6386 save  will  store  an  image  produced  by  GRASS  display  programs  like  didisplay ,  d.rast,  etc. 
from  the  graphics  screen  to  the  6386  hard  disk. 

NOTES 

This  program  is  available  for  PG6386  UNIX  workstations,  only. 

SEE  ALSO 

d.6386save,  d.6386. show 

AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHQ-CGIS 
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NAME 

d.6386jave  -  Stores  screen  images  to  the  PG6386  hard  disk. 

(SCS  GRASS  Display  Program) 

(Available  for  PC6386  UNIX  workstations,  only) 

SYNOPSIS 

d.6386.save 
d. 6386 .save  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively  save  PC6386  screen  images  produced  by  GRASS  display 
programs  ( d.display ,  d.rast,  etc.)  to  the  P06386  hard  disk.  It  will  assign  the  extension  ".GRS"  to  the 
filename  given,  and  will  store  the  image  file  in  the  user’s  current  directory.  The  files  are  binary  image 
files,  representing  the  red,  green,  and  blue  planes  of  the  display  board  graphic  memory. 

NOTES 

This  program  is  available  for  PG6386  UNIX  workstations,  only. 

SEE  ALSO 

d.6386 delete,  d.6386jhow 
AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHOCCHS 
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NAME 

d.6386jhow  -  Reads  screen  images  stored  on  the  PC6386  hard  disk  by  d.6386jave. 

(SCS  GRASS  Display  Program) 

(Available  for  PC6386  UNIX  workstations,  only) 

SYNOPSIS 

d.6386jshow 
d.6386.shaw  help 

DESCRIPTION 

d.6386jhow  allows  a  user  to  interactively  view  PC6386  screen  images  produced  by  GRASS  display 
programs  ( d.display ,  d.rast,  etc.)  and  saved  to  the  P06386  hard  disk  by  d.6386jave. 

NOTES 

This  program  is  available  for  PC6386  UNIX  workstations,  only. 

SEE  ALSO 

d.6386.delete,  d.6386^ave 

AUTHOR 

P.  W.  Carlson,  USDA  SCS,  NHQ-CGIS 
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NAME 

d.tojites  -  Allows  the  user  to  create  a  GRASS  site_lists  file  by  selecting  points  on  the  graphics 
monitor  with  a  mouse. 

(SCS  GRASS  Map  Development  Program) 

SYNOPSIS 

d.twsitts 
d.t&ates  help 
d.to^sites  sites  =name 

DESCRIPTION 

This  program  allows  a  user  to  create  a  new  GRASS  sitejists  file  by  selecting  locations  within  the 
active  display  frame.  The  user  is  prompted  for  the  label  that  is  placed  in  the  sitejists  file  with  the 
corresponding  geographic  coordinates. 

COMMAND  LINE  OPTIONS 
Parameter: 

sites  name  The  name  to  be  assigned  to  the  GRASS  site  Jist  file  to  be  created. 

EXAMPLE 

For  example,  to  create  a  sitejists  file  called  SAMPLE; 

d.toLaites  sites— SAMPLE 
The  user  is  prompted  as  follows: 

Enter  the  label  to  place  in  the  site  file  :  SAMPLE 

Buttons 

Left:  Place  Label  Here 
Middle:  Change  the  label 
Right:  Quit 

Note:  The  sitejists  file  must  not  already  exist. 

SEE  ALSO 

d.frame,  d.what,  d.zoom,  d.sites,  s.db.rim,  s.menu 

AUTHOR 

M.  L.  Holko,  USDASCS,  NHUCGIS 


GRASS  4.0  (Summer  1991) 


US.  Army  CI  RI. 


458 


m.bsplit 


GRASS  Reference  Manual 


m.bspiit 


NAME 

nubsplit  -  Splits  a  large  (greater  than  1,048,000  megabyte)  file  into  smaller  portions. 

(SCS  GRASS  File  Management  Program) 

SYNOPSIS 

mi>spiit 
m J»  split  help 

mJj split  input  name  [size=value]  [  prefix  name ] 

DESCRIPTION 

nubsplit  works  much  like  the  UNIX  command  csplit",  however,  it  was  developed  to  be  used  an  binary, 
not  ASCII,  files. 

The  first  parameter,  size,  has  a  default  value  of  500000.  The  user  may  assign  larger  or  smaller  values, 
as  long  as  1000000  is  not  exceeded. 

The  second  parameter,  prefix,  is  comparable  to  the  UNIX  csplit  command  use  of  "x"  as  a  prefix  to 
output  files,  nubsplit  uses  the  default  of  "bx”  as  a  prefix  on  output. 

COMMAND  LINE  OPTIONS 
Parameters: 

input  =name  The  name  of  the  binary  input  file  to  be  split. 

si/e  =value  The  value,  in  megabytes,  of  one  of  the  new,  split-up  files  created  from  the  input 

file. 

prefix  =name  File  name  prefix  assigned  to  the  new  (split)  files. 

SEE  ALSO 

The  UNIX  csplit  command. 

AUTHOR 

R.  I ..  Glenn,  USDA  SCS,  NHQ-CGIS 
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NAME 

nueigensystem  -  Computes  eigen  values  and  eigen  vectors  for  square  matricies. 

(GRASS  Data  Import/Processing  Program) 

SYNOPSIS 

m.eigensystem  <  input fUe 
DESCRIPTION 

nueigensystem  determines  the  eigen  values  and  eigen  vectors  for  square  matricies.  The  inputfile  must 
have  the  following  format:  the  first  line  contains  an  integer  K  which  is  the  number  of  rows  and  columns 
in  the  matrix;  the  remainder  of  the  file  is  the  matrix,  i.e.,  K  lines,  each  containing  K  real  numbers.  For 
example: 

3 

462.876649  480.411218  281.758307 

480.411218  513.015646  278.914813 

281.758307  278.914813  336326645 

The  output  will  be  K  groups  of  lines;  each  group  will  have  the  format: 

E  real  part  imaginary  part  relative  importance 

V  real  part  imaginary'  part 

...  K  lines  ... 

N  real  part  imaginary  part 

...  K  lines  ... 

W  real  part  imaginary  part 

...  K  lines  ... 

The  E  line  is  the  eigen  value.  The  V  lines  are  the  eigen  vector  associated  with  E  The  N  lines  are  the 
V  s  ector  normalized  to  have  a  magnittide  of  1.  The  W  lines  are  the  N  vector  multiplied  by  the  square 
root  of  the  magnitude  of  the  eigen  value  (E). 

For  the  example  input  matrix,  the  output  would  be: 


E 

1159.7452017844 

0.0000000000 

V 

0.6910021591 

0.0000000000 

V 

0.7205280412 

0.0000000000 

V 

0.4805108400 

0.0000000000 

N 

0.6236808478 

0.0000000000 

N 

0.6503301526 

0.0000000000 

N 

0.4336967751 

0.0000000000 

W 

21.2394712045 

0.0000000000 

W 

22.1470141296 

0.0000000000 

w 

14.7695575384 

().()( KKKXXXXX) 

I 

5.9705414972 

O.OtXXXXXXXX) 

V 

0.71 19385973 

O.tKXXXXXXXX) 

V 

-0.6358200627 

O.(XXXXXXXXX) 

V 

-().( 1703936743 

O.(XXXXXXXXX) 

N 

0.7438340890 

O.O(KKXXXXXX) 

N 

0.6643053754 

O.OtXXXXXXXX) 

N 

-0.0735473745 

O.(KXKXXXXXX) 

W 

1 .8175356507 

O.(MXXXXXXXX) 

W 

1 .0232096923 

O.tMKX  KXXXXX) 

w 

0.1797)07407 

III  xi(  XX  XX  XXX) 

(  'l\ANS  4,0  (Summer  l‘>9l  l 
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E  1463031967184 

V  02265837636 

V  03474697082 

V  -03468727535 

N  02402770238 

N  03684685345 

N  0.8980522763 

W  2.9082771721 

W  4.4598880523 

W  -103698904856 


OjOOOOOOOOOO  11.16 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 
0.0000000000 


PROCRAM  NOTES 

The  relative  importance  of  the  eigen  value  (E)  is  the  ratio  (percentage)  of  the  eigen  value  to  the  sum  of 
the  eigen  values.  Note  that  the  output  is  not  sorted  by  relative  importance. 

In  general ,  the  solution  to  the  eigen  system  results  in  complex  numbers  (with  both  real  and  imaginary 
jxirts).  1  low  ever,  in  the  example  above,  since  the  input  matrix  is  symmetric  (i.e.,  inverting  the  rows  and 
cohunns  gives  the  same  matrix)  the  dgen  system  has  only  real  values  (i.e.,  the  imaginary  part  is  zero). 
This  fact  makes  it  possible  to  use  eigen  vectors  to  perform  principle  component  transformation  of  data 
sets.  The  covariance  or  correlation  matrix  of  any  data  set  is  symmetric  and  thus  has  only  real  eigen 
values  and  vectors. 

PRINCIPLE  COMPONENTS 

To  perform  principle  component  transformation  on  GRASS  data  layers,  one  would  use  r.cwar  to  get 
the  covariance  (or  correlation)  matrix  for  a  set  of  data  layers,  nueigensyslem  to  extract  the  related 
eigen  vectors,  and  r.mapcalc  to  form  the  desired  components.  For  example,  to  get  the  eigen  vectors 
for  3  layers: 

(echo  3;  r.covar  map.l^iup.2^nap3)  j  m.eigensystem 

Note  that  since  m.covar  only  outputs  the  matrix,  we  must  manually  prepend  the  matrix  size  (3)  usin^ 
the  echo  command. 

Then,  using  the  W  vector,  new  maps  are  created: 

ran  ape  ale  ’pc.l  =212395*  map. 1  +  22.1470*  map2  + 14.7696*  map3’ 

r.ma|xalc  ’pc.2  =  2.9083*map.l  +  4.4599*map.2  -  10.8699*map3’ 
r.mapcalc  ’pc3  =  13175*map.l  -  1 .6232* niap.2  -  0.1797*map3’ 

NOTES 

The  source  axle  for  this  program  lives  under  /src.contrib/CiERIVmi  sc /m.eigensystem  and  requires  a 
Eortnur  compiler. 

SEE  ALSO 

r.cwar,  r.mapcalc,  r.pca,  r. rescale 

AUTHOR 

This  code  uses  routines  from  the  ITSl'AC  K  system,  llic  interface  was  coded  by  Michael  Shapiro,  U.S. 
Anny  C onstmetion  Irigincering  Research  laboratory 
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NAME 

mgeo  -  Calculates  conversion  coordinates  for  geographic  positions. 

(SCS  GRASS  Map  Development  Program) 

SYNOPSIS 

m.geo 
m-geo  help 

DESCRIPTION 

This  program  allows  a  user  to  interactively:  convert  projection  coordinates  Northings  and  Eastings  to 
Latitude  and  Longitude  values,  or 

allows  a  user  to  interactively:  convert  Latitude  and  Longitude  values  to  projection  coordinate  Northings 
and  Eastings. 

It  allows  a  user  to  do  all  of  the  above:  reading  from  a  file,  writing  to  the  screen,  or  rearing  from  the 
keyboard,  writing  to  a  file,  or  reading  from  a  file,  writing  to  a  file. 

Note:  The  program  does  not  transform  GRASS  files,  it  is  designed  to  determine  coordinate  values  cm 
an  individual  position. 

Several  map  projections  are  currently  supported: 

stp  -  State  Plane,  for  all  CONUS,  Alaska,  Hawaii,  Puerto  Rico,  Guam,  Virgin  Islands,  American  Samoa, 
Northern  Mariana  Islands,  Palau,  and  U.S.  Minor  Outlying  Islands 

airy  -  Airy-F 

aea  -  Albers  Egual  Area-FI 
apian  -  Apian  Globular  I  F 
aeqd  -  Azimuthal  equidistant-FI 
aitoff  -  Aitoff  F 
august  -  August  Epicycloidal-F 

bacon  -  Bacon  Globular-F 
bipc  -  Bipolar  Conic-FI 
boggs  -  Boggs  Eumorphic-F 
bonne  -  Bonne-FI 

cass  -  Cassini-FI 
cc  -  Central  Cylindrical- FT 
cea  -  Cylindrical  Equal  Area-FI 
collg  -  Collignon-FI 

dense  -  Denoyer  Semi-Elliptical-F 

eckl  -  Frkert  I- FI 

eck3  -  Eckert  ni-FI 

eck5  -  Fxkcrt  V-FI 

eisen  Fiscnlohr-F 

eqc  -  Equidistant  Cylindrical-El 

cqdc  -  Equidistant  Conic- IT 

foum  -  Fournier  Globular- 1 

gall  -  C kill  (Stereographic)  IT 
goode  -  Cxxxle  Ilomolosinc  F 
gnom  -  (/nomonic-FI 

liarruner  I  Lunnicr  (Elliptical)- 1 
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hataea  -  Haiano  Asymmetrical  Equal  Area-FI 
lag  mg  -  Lagrange-F 

laea  -  Lambert  Azimuthal  Equal  Area-FI 
leac  -  Lambert  Equal  Area  Conic- FI 
lcc  -  Lambert  Conformal  Conic-FI 
loxim  -  Loximuthal-FI 

mbtfpp  -  McBryde-Thomas  Flat-Polar  Parabdic-FI 
mbtfps  -  McBryde-Thomas  Flat-Polar  Sinusddal-FI 
mbtfpq  -  McBryde-Thomas  Flat-Polar  Quartic-FI 
mere  -  Mercator- FT 
mill  -  Miller-FI 
moll  -  Mollweides-FI 

nied  -  Nicdosi  CRobular-F 

nsper  -  General  Vertical  Perspective- FI 

ocea  -  Oblique  Cylindrical  Equal  Area-FI 
omerc  -  Oblique  Mercator- FI 
ortel  -  Ortelius-F 
ortho  -  Orthographic  FI 

parab  -  Caster  Parabdic-FI 
pconic  -  Perspective  Conic-F 
poly  -  Pdyconic  (American)-FI 
putp2  -  Putnins  P2’-FI 
putp5  -  Putnins  P5-FI 

quau  -  Quartic  Anthalic-FI 

rpoly  Rectangular  Pdyconic-  F 
robin  -  Robinson -FI 

sinu  Sinusoidal  -FI 
stere  -  Stercogra[Tliic-FI 

tcc  Transverse  Centra)  Cylindrical- FI 

tcea  Transverse  Cylindrical  Equal  Area-FI 

tmerc  -  Transverse  Mercator-FI 
tpers  lilted  perspective- FT 

ups  Univ  ersal  I’dar  Stcreographic-FI 
utm  Universal  Transverse  Mercator-FI 

vantlg  Van  der  (irinten- 1 1 
vnntlg2  Van  tier  (irinten  H  I 
vandg3  Van  der  (irinten  III  I 
vantlg4  Van  tier  C irinten  IV  F 

wag 7  -  Wagner  VII  F 

wink  I  Winkcl  I  I  I 
wintri  Winkel  Tri|x.'l-F 
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Each  of  the  above  projections  (with  the  exception  of  State  Plane)  can  be  computed  with  the  following 
spheroids: 

MERIT  -  MERIT  1983 

GRS80  -  GRS  1980(IUGG,  1980) 

IAL776  -  IALJ 1976 

airy  -  Aiiy  1830 

aust_ntl  -  Australian  Natl,  S.  Amer.,  IALJ  64 

GRS67  -  GRS  67(IUGG  1967) 

bessel  -  Bessel  1841 

clrk66  -  Clarke  1866 

clik80  -  Gaike  1880  mod. 

everest  -  Everest  1830 

hough  -  Hough 

inti  -  International  1909  (Hayford) 

krass  -  Krassovsky,  1942 
mercury  -  Mercury  1960 
mod_airy  -  Modified  Airy 
mocLever  -  Modified  Everest 
modjmerc  -  Modified  Merc  1968 
newjntl  -  New  International  1967 
SEasia  -  Southeast  Asia 
walbeck  -  Walbeck 
WGS66  -WGS66 
WGS72  -  WGS  72 
sphere  -  Sphere  of  6370997  m 

INPUT  FILE  FORMAT 

When  reading  from  a  file  of  I  AITllJIXTlXWirilJI^-:  data  the  file  will  contain  three  (3)  columns  of 
information: 

the  first  column  -  latitude  -  in  degrees  minutes  seconds, 
the  second  column  -  longitude  -  in  degrees  minutes  seconds, 
fire  third  column  -  zone  -  zero(0)  if  not  required. 

For  example: 

440  36  31.4563  -87  2  7.8193  16 

40n  36  31.4563  87w  2  7.8193  16 

When  reading  from  a  file  of  PROJECTION  CXXJREHNATES  data  the  file  will  contain  three  (3) 

columns  of  information: 

the  first  column  -  easting  -  ground  coordinates 

the  second  column  -  northing  -  ground  coordinates 

the  third  column  -  zone  -  zero(0)  if  not  required. 

For  example: 

500000.00  44969 18.64  16  <-  utm 

424489.11  1908736.13  0  <-  lambert 

Note:  NO  column  headings  are  required,  just  the  numbers. 

SEE  ALSO 

Mapgen,  proj 

AUTHOR 

R.  L.  Glenn,  USDA  SCS,  NHOCGIS 
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NAME 

rn.get.fips  -  Finds  a  state  and  county  FIPS  code  for  the  user. 

(SCS  GRASS  Data  Inport/Processing) 

SYNOPSIS 

in.get.lips 
m .get .tips  help 

DESCRIPTION 

rn.get.fips  prompts  the  user  for  a  State  FIPS  or  two-letter  state  abbreviation  code,  and  then  for  the  name 
of  a  county  located  in  that  state.  The  program  then  prints  the  State  and  County  FIPS  code  numbers  to 
the  user’s  terminal  screen  (standard  out). 

EXAMPLE 

rn.get.fi  ps 

Enter  State  FIPS  code  or  press  RETURN  if  unknown: 

Enter  Two- Letter  State  or  Territory  Abbreviation:  pa 
Fatter  County  Name:  cambria 
42  21 

AUTHOR 

M.  L.  Ifclko,  USDA  SCS,  NHQ-CGIS 
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NAME 

nuget^tp  -  Finds  a  State  Plane  projection  zone  code  for  the  user. 

(SCS  GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

in.get.stp 
mget-stp  help 

DESCRIPTION 

mgetJtp  prompts  die  user  for  a  State  FIPS  code  or  two-letter  stale  abbreviation,  and  then  for  the  name 
of  a  county  located  within  this  state.  The  program  then  prints  to  standard  output  the  USGS  State  Plane 
zone  code  number  associated  with  this  county. 

EXAMPLE 

rn.get.8tp 

Enter  State  FIPS  code  or  RETURN  if  unknown: 

Enter  Two-Letter  State  or  Territory  Abbreviation:  pa 

filter  County  Name:  cambria 

3702 

AUTHOR 

M.  L.  Ffolko,  USDA  SCS,  NHOCGIS 
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NAME 

nuqcalc  -  Creates  tables,  performs  conversions,  and  performs  simple  math  calculations. 

(SCS  GRASS  Data  Import/Processing  Program) 

SYNOPSIS 

m-qcalc 
m-qcalc  help 

majestic  [-sahem]  init  va/ue  [eud— value]  (incr  =vaiue]  [unit  =name] 

DESCRIPTION 

lhis  program  allows  the  user  to:  *  Create  a  table  of  cell  sizes,  showing  how  many  square  feet,  acres, 
and  hcctacres  each  cell  would  represent 

*  Create  a  table  of  acreage  sizes,  shewing  how  many  square  feet,  hectacres,  and  what  cell  size  would 
be  represented 

*  Create  a  table  of  hectare  sizes,  showing  how  many  square  feet,  acres,  and  what  cell  size  would 
represented  *  Convert  values  among  feet,  meters,  miles,  and  kilometers 

*  Allows  a  user  to  use  the  UNIX  be  simple  math  calculator 

COMMAND  LINE  OPTIONS 


Flags: 

-s 

Create  a  cell  size  table. 

•a 

Create  an  acres  size  table. 

-h 

Create  a  hectares  size  table. 

-c 

Convert  value  to  user-stated  units. 

-m 

Perform  a  math  calculation. 

Parameters: 

init  -value 

Initial  value. 

end  —value 

finding  value. 

incr  =value 

Increment  value. 

unit  =name 

Units  of  measure. 

Options:  ft.  mt,  mi,  km 

EXAMPLE 

'I lie  following  command  produces  the  subsequent  table: 

g.qcalc  -s  i nit  =100  end  =400  incr  =100 


(ill  Size 

Sq.Ft. 

Acres 

Hectares 

100  x  100 

107639.31 

2.47 

1.00 

200  x  200 

430557.23 

9.8S 

4.00 

300  x  300 

968753.77 

">'>  -M 

9.00 

400  x  400 

1722228.93 

39  54 

16.00 

'llio  following  command  produces  the  subsequent  table: 

g.qcalc  -c  init=100  unit=ft 

leet  Meters  Miles  Kilometers 

100.0  30.4  0.02  0.03 

AUTHOR 

K.  L  Glenn.  USDA  SCS,  NUQ-CGIS 
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NAME 

nLsetproj  -  Allows  the  user  to  create  the  PRQLINFO  and  the  PROJ_UNTTS  files  to  record  the 
projection  information  associated  with  a  specified  mapset. 

(SCS  GRASS  Data  Impor.  /Processing  Progtam) 

SYNOPSIS 

m^etproj 
m  jet  proj  help 

m^Klproj  [set  =name]  proj  name 
DESCRIPTION 

nusetproj  allows  a  user  to  create  a  new  PRQLINFO  file  in  the  specified  mapset.  The  file  is  used  to 
record  the  projection  info,  anon  associated  with  the  specified  mapset. 

Note: 

The  "set”  mapset  must  exist  and  must  not  contain  a  PRQLINFO  or  PRQLUNITS  file. 

The  specification  of  any  projection  other  than  11  and  xxx  will  generate  a  request  to  the  user  for 
a  name  of  a  standard  ellipse. 

The  projections  of  aea,  lcc,  mere,  and  tmerc  will  generate  a  request  to  the  user  for  the  prime 
meridian  and  standard  parallel  for  the  output  map. 

The  projection  of  stp  will  generate  a  request  to  the  user  for  the  suite  abbreviation  and  choice  of 
zone  for  the  output  map. 

The  projection  of  xxx  will  request  mapgen  proj  parameters.  See  the  mapgen  proj 
documentation  for  the  uses  of  this  software. 

COMMAND  LINE  OPTIONS 
Parameters: 

set  name 

Mapset  in  which  the  projection  information  file  is  to  be  stored. 

proj  =name 

Map  projection  name. 

Options:  utm,  aea,  stp,  11,  lcc,  mere,  trnerc,  xxx 

SEE  ALSO 
EXAMPLE 

To  create  a  PRQLINl-O  file  recording  mapset  SAMPLE  as  being  a  UTM  projection  in  zone  13: 

mjetproj  set  =S AMPLE  proj  =utm 

The  user  will  be  prompted  for  the  spheroid  and  zone  of  the  UTM  projection. 

SEE  ALSO 

Mapgen  proj 

AUTHOR 

M.  I..  Holko,  USDA  SCS,  NHQ-CGIS 
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NAME 

rn.stp.proj  -  Finds  a  State  Plane  projection  for  the  user. 

(SC5  GRASS  Data  Import /Processing  Program) 

SYNOPSIS 

in.stp.proj 
m-slp.proj  help 

DESCRIPTION 

rn.stp.proj  prompts  the  user  for  a  state  FTPS  code  or  its  two-letter  abbreviation,  and  then  for  the  name 
of  a  county  located  within  this  state.  The  program  then  prints  the  MAPGEN  style  parameters  for  the 
State  Plane  Projection. 

EXAMPLE 

rn.stp.proj 

Fnter  State  FTPS  code  or  press  RETURN  if  unknown: 

Fnter  Two-Letter  State  or  Territory  Abbreviation:  pa 
Fnter  County  Name:  cambria 

+proj=lcc  +a=0.63782064e+07  +es=0 .676865799729 1 094e-02  +x_0=0.6096012192024384e+06 
+y_0=0  +lon_0=77d45’w  +lat_0=39d20’n  +lat_l=40d58’n  +lat_2=39d56’n 

AUTHOR 

M.  I„  Holko,  USDA  SCS,  NHOCGIS 
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NAME 

r.in.erdas  -  Creales  raster  files  from  ERDAS  files.  It  creates  one  raster  file  for  each  band,  and  creates 
color  support  if  an  ERDAS  trailer  file  is  specified. 

(SCS  GRASS  Raster  Program) 

SYNOPSIS 

rJn.erdas 
rJn.erdas  help 

rjn.erdas  erdnsname  [trl  =name]  prefix  =name 
DESCRIPTION 

This  command  prompts  the  user  twice: 

first  the  user  is  asked  if  he  wishes  to  select  a  subset  of 
the  bands  available  in  the  ERDAS  file  for  output. 

If  unspecified  by  the  user,  all  bands  are  used,  by  default. 

Second,  the  user  is  asked  if  he  wishes  to  select  a  subregion 
of  the  image  available  in  the  ERDAS  file.  If  unspecified  by  the 
user,  the  complete  image  is  used,  by  default. 


Note: 

GRASS  raster  files  will  be  named  preftxJxmd 

Remember  that  it  is  necessary  to  run: 

r.support:  to  create  the  histogram  or  change  the  color  table. 

i.group :  to  associate  the  individual  raster  files  as  an  image  group. 

COMMAND  LINE  OPTIONS 
Parameters: 

erdas  name  Input  ERDAS  file  name. 

trl  =name  Input  ERDAS  trailer  file  name. 

prefix  name  Prefix  of  the  GRASS  raster  files  to  be  created. 


AUTHOR 

M.  L.  Efolko,  USDA  SCS,  NHQ-CGIS 
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NAME 

r. in. niads  -  Converts  a  MIADS  output  ASCII  text  file  into  an  GRASS  raster  import  ( run. ascii ) 
formatted  file. 

(SCS  GRASS  Raster  Program) 

SYNOPSIS 

rJnjnlads 
rJn.mlads  help 

rinaniads  input  =name  output  name  strip  value  \in*=value  *11  =value 
Northing  —value  Easting  =value  siz c=value 

DESCRIPTION 

r.in.miads  allows  a  user  to  create  a  r.in.ascii  formatted  ASCII  file  from  a  MIADS  output  printer 
format  ASCII  file. 

Ihe  program  will  actively  read  the  MIADS  data  file,  selectively  remove  and  process  each  strip,  creating 
a  individual  r.in.ascii  formatted  file  for  each  strip,  and  finally  create  one  category  file  for  all  strips. 
Ihe  program  also  produces  a  report  file  summarizing  all  pertinent  information  for  each  strip. 

Ihe  resulting  r.in.ascii  files  for  each  strip  are  then  used  in  conjunction  with  the  GRASS  commands 
r.in.ascii  and  r. patch  to  create  a  complete  raster  file. 


COMMAND  LINE  OPTIONS 

Parameters: 

input  name 

MIADS  input  file  name. 

output  =name 

GRASS  raster  data  output  file  name. 

strip  -value 

MIADSs  strip  number  of  reference  cell. 

lin  revalue 

MIADSs  line  number  of  reference  cell. 

cell  =value 

MIADS  cell  number  of  reference  cell. 

Northing  =value 

UrM  Fasting  at  the  cell  reference. 

Easting— va/ue 

UlM  Northing  at  the  cell  reference. 

si  t.K=value 

Cell  size  (length  one  side)  in  meters. 

SC'S  has  developed  scripts  tun.  mi  ads.  getstrip,  and  strip. 99s.  These  scripts  make  the  MIADS  to 
( iRASS  conversion  easier. 

run. niads 

SC  S  macro  to  jx-rfonn  the  complete  conversion  of  a  MIADS  printer  format  data  set  to  a 
( iRASS  raster  file. 

getstrip 

Reads  each  MIADS  strip  file  and  converts  it  to  a  independent  GRASS  data  file.  Support  may 
lx-  mil  on  any  one  of  these  strip  files;  however,  there  is  no  category  information  available, 
bach  strip  tnav  lx-  viewed  at  this  time  with  d.rast  or  d.display. 

strip.  99. s 

S|xcial  pro  r.in.miads  macro  that  removes  the  99’s  from  the  MIADS  data  file.  Iliis 
effectively  removes  Under  information,  replacing  it  with  "no  data"  values. 

SEE  AI.SO 

d.display,  d.rast,  r.in.ascii,  r.patch,  r.support 

AUTHOR 

r.in.niads  R.  I,.  Glenn,  USD  A  SC  S,  NIKX'GIS 

rim. niads,  strip. 99s  Hamid  Kane.  USDA  SC  'S.  Oklahoma  Stale  Office 
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NAME 

r.reclass  jcs  -  Create  a  new  raster  map  layer  based  on  an  existing  raster  map. 

(SCS  GRASS  Raster  Program) 

SYNOPSIS 

rj'eclass.scs 
r .reclass. scs  help 

DESCRIPTION 

r.reclass  jcs  is  an  interface  to  the  GRASS  r.reclass  program.  The  program  will  reclassify  the 
category  values  in  a  raster  map  layer  based  on  reclass  instructions  entered  by  the  user.  The  user  can 
enter  map  reclassification  rules  to  r.reclass.scs  either  from  standard  input  or  from  a  file.  The  program 
then  issues  r.reclass  commands  to  produce  the  new’  reclassified  raster  map  layer. 

Input  to  r.reclass.scs  consists  of  a  list  of  category  names  c«-  category  values  that  will  be  grouped  into 
the  same  category  in  the  output  (reclassified)  map.  Only  one  category  name  should  appear  on  each  line 
of  input.  Input  can  be  entered  either  interactively,  or  from  a  file. 

A  file  containing  these  reclass  rules  can  be  created  using  a  text  editor,  word-processor,  DBMS,  etc.  It 
is  no  more  than  a  list  of  category  names  which  will  have  the  same  category  value  after  the 
reclassification. 

SEE  ALSO 

r.reclass ,  r. resample,  r.rescale 

AUTHOR 

R.  L.  Glenn,  USDASCS,  NHOCGIS 


GRASS  4.0  (Summer  1991) 


U  S.  Army  CI  RI 


472 


s.to.vect 


GRASS  Reference  Manual 


s.to.vect 


NAMK 

s.to.vect  -  Converts  a  GRASS  sitejists  file  into  a  vector  file. 

(SCS  GRASS  Sites  Program) 

SYNOPSIS 

s.to.vect 
s.to.vect  help 

s.to.vect  input  =name  output  name 
DESCRIPTION 

s.to.vect  converts  GRASS  sitejists  file  into  vector  files.  The  resulting  vector  file  can  be  treated  as  any 
other  vector  file.  The  requirements  of  the  sitejists  file  are  standard  (i.e.,  a  regular  sitejists  file  format 
is  required).  Sitejists  file  values  are  used  as  dig_cats  category  values. 

COMMAND  LINE  OPTIONS 
Parameters: 

input  =name  Name  of  input  GRASS  sitejists  file  to  be  converted, 

output  name  Name  to  be  assigned  to  the  vector  output  file. 

AUTHOR 

R  L.  Glenn,  USDA  SCS,  NHOCGIS 
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NAME 

v.export  ~  Converts  binary  vector  files  into  formatted  ASCII  files  for  transfer  to  other  computer 
systems. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.export 
v.export  help 

DESCRIPTION 

This  program  performs  all  of  the  processes  that  are  needed  to  convert  binary  vector  files  into  formatted 
ASCII  files. 

It  also  creates  support  files: 

-  an  attribute  flat  file,  which  contains  information  for  each  area  in  the  DIG  file  -  i.e.,  the  DLG 
area  number,  the  GRASS  area  label,  and  the  GRASS  category  code  (only  created  when 
exporting  in  DLG  format); 

-  an  attribute  file  which  contains  the  information  from  the  dig_att  file  (only  created  when 
exporting  ASGI  vector  format). 

EXPORT  FILES 

After  entering  the  command  v.export,  the  user  will  be  asked  which  type  of  file  to  export: 

Be  ports  from  GRASS  Vector  ( v. digit )  Format 

1  -  ASCII  DLG  file  from  GRASS  Vector  Format 

2  -  ASCII  DIGIT  file  from  GRASS  Vector  Format 

3  -  ASCII  SCS-GEF  file  from  GRASS  Vector  Format 

4  -  ASCII  ARC/INFO  file  from  GRASS  Vector  Format 

5  -  ASCII  DXF  file  from  GRASS  Vector  Format 

If  numbers  1-4  are  chosen,  v.export  will  respond  with  a  request  for  the  vector  file  name.  After  the  user 
enters  the  file  name  the  program  proceeds  to  create  the  respective  output  format  files. 

GRASS  Vector  to  DLG  File 

Converts  binary  v  ector  files  (such  as  those  created  by  v. digit)  to  a  DIG  file  and  creates  the  attrilviite 
file.  Both  files  are  placed  in  the  dig  directory  under  a  user  selected  name;  the  attribute  file  has  jitt 
appended. 

GRASS  Vector  file  into  ASCII  Vector  File 

Converts  a  bin;irv  vector  file  into  a  readable  ASCII  file.  Both  files  are  placed  ini  the  dig_ascii 
directory  under  the  same  name  as  the  given  vector  file,  the  attribute  file  has  .att  appended. 

GRASS  Vector  to  SCS-GEF  File 

Converts  binary  vector  files  to  SCS-GEF  files.  Creates  the  SCS-GFJ  header,  lines,  text.  ;uid  feature 
files.  All  files  are  created  and  placed  in  a  SIGCAIION/gef  directory  as  a  single  l  NIX  file  under  a 
aser  selected  name. 

The  folk  wing  is  the  SCS-GFJ  file  structure: 
header  record  1 

I  i 

header  record  n 
head 

line  record  1 

I  I 

line  record  n 
-line 
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text  record  1 

I  I 

text  record  n 
-text 

feature  record  1 

I  I 

feature  record  n 
-feat 

Ihe  user  will  be  required  to  use  standard  UNIX  commands  to  separate  this  file  into  individual  files  as 
required  by  SCS-GEF  specifications. 

GRASS  Vector  to  ARC/INKXgenerated)  file 

(Converts  binary  vector  files  to  a  "ARC  ungenerate"  format.  A  GRASS  vector  file  to  be  exported  to 
ARC/INK)  mast  be  either  a  line  coverage  (must  contain  only  lines)  or  a  polygon  coverage  (must 
contain  only  area  edges).  Both  "ungenerate  lines  and  points"  files  are  created  and  are  placed  in  a 
SI/X'AHON/arc  directory  under  a  user  selected  name. 

Ihe  binary  vector  name  will  be  used  to  name  the  varioas  files  that  will  be  created  for  export  to 
ARCVlNIO.  In  the  case  of  a  labeled  polygon  coverage,  the  following  three  files  will  be  created:  a 
lines  file  with  the  suffix  Jin,  a  label-points  file  with  the  suffix  Jab,  and  a  label-text  file  with  the  suffix 
.txt. 

In  the  case  of  a  line  coverage  the  following  two  files  will  be  created:  a  lines  file  with  the  suffix  Jin,  and 
a  label  text  file  with  the  suffix  .txt. 

An  unlabelcd  polygon  or  line  covenge  will  result  in  a  lines  file  (Jin  suffix)  only.  See  the  DATAFILE 
I-ORMAIS  section  of  v. import  for  more  information  on  these  files. 

GRASS  Vector  to  DXF  file 

Converts  binary  vector  files  to  a  "DXF’  format. 

NOILS 

Support  files  mast  be  built  using  the  GRASS  program  v.support  before  exporting  any  vecto 
file. 

Other  ASCII  formats  are  useful  when  importing/exporting  data  into  and  from  GRASS.  Such 
data  tiles  should  lie  in  ASCII  format  w  hen  transferred. 

SKK  ALSO 

v.digil,  v. import  v.out.arc,  v. out. ascii,  v.out.dlg,  v.oui.iHgscs,  v.out.dxf,  v.outjcsgef,  v.support, 

AUTHOR 

R.  I..  Glenn.  IJSDA  S(  S,  NI 10 CGIS 
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NAME 

v. extract  ~  Selects  vectors  from  an  existing  vector  map  and  creates  a  new  map  containing  only  the 
selected  vectors. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.  extract 
v  .extract  help 

v.extractFR  [tta]  typ e=name  input  name  output  =name  new  =value 
[list=range]  [file  =name] 

DESCRIPTION 

v.extract  allows  a  user  to  create  a  new  vector  map  layer  from  an  existing  vector  map  layer.  User 
provides  the  program  with  category  numbers  or  option  (n)  names,  input  vector  file  name,  an  output 
vector  name,  and  the  type  of  input  map.  There  is  an  option  (d)  to  dissolve  common  boundaries 
between  adjoining  map  areas  in  the  same  category  list.  The  user  may  specify  a  file  containing  category 
values  or  names. 

Note: 

The  dissolve  option  will  work  on  only  those  areas  which  are  in  the  given  category  list.  If  a 
map  area  is  inside  (island)  a  listed  category'  area  and  is  NOT  in  the  given  category  list,  its 
boundaries  are  output  to  the  resultant  map. 

COMMAND  LINE  OPTIONS 


Flags: 

-d 

Dissolve  common  boundaries  (default  is  no) 

-n 

Use  category  names  NOT  category  values. 

Parameters: 

type  name 

Select  area,  line,  or  site. 

Options:  area,  line,  site 

input  =name 

Input  vector  map  name. 

output  =name 

Output  vector  map  name. 

new  —value 

Biter  0  cm-  a  desired  NEW  category  value. 

list  ^range 

Category  ranges. 

For  example:  1 , 3-8,  13 

For  example:  Abe,  I>sf2,  XyZ 

file  name 

Text  file  name  fix  category  range/list  . 

EXAMPLE 

$GISBASK/etc/v  .extract  -d  list=4 ,2,3,4  &\ 
input  soils  output  =soil_gruu pa  type=area  new -  I 

lYoduces  a  new  vector  area  file  soil_groupa  containin'  ’area’  Ixxuularics  from  soils  w  ith  area  categorv 
values  of  1  thm  4;  any  common  boundaries  arc  dissolved,  aixl  all  areas  of  the  new  map  will  Iv 
assigned  category'  value  1 . 

$GISBASK/etc/v. extract  -dn  list=Abc,Dc»  I,12A,W  Wd  &\ 
input  soils  output  =suil_groupa  type=area  new  0 

Bixluces  a  new  vector  area  file  soil_groupa  containing  ’area’  Ixxindarics  from  soils  with  area  i nlcgors 
names  of  Abc,I>cfl.  12A.WWd;  these  names  correspond  to  values  I  thru  4  of  soils  Am  eomniou 
boundaries  are  dissolved,  all  areas  of  the  new  map  will  retain  their  original  categon  values  I  thm  4.  m 
this  case,  since  new  was  set  to  0. 
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$GISBASE/etc/v .extract  -n  input  =soils  output  =so*l_groupo  &\ 
typearea  new  =1  tile  =sara pie 

Produces  a  new  vector  area  file  soil^groupa  containing  ’area’  boundaries  from  soils.  No  common 
boundaries  are  dissolved,  all  areas  of  the  new  map  will  be  assigned  category  value  1.  The  "names*'  (-n 
option)  can  be  found  in  the  file  sample  of  the  current  directory. 

The  format  for  "sample"  is: 

Abe 

Defl 

12A 

WWd 

AUTHOR 

R  L.  Genii,  USDA  SCS,  NHQ-CXHS 
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NAME 

v import  -  SCS  user  interface  to  GRASS  import  programs. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

vimporl 
v .import  help 

DESCRIPTION 

This  program  performs  all  of  the  processes  that  are  needed  to  convert  ASCII  DLG  files,  binary  DLG 
files,  ASCII  SCS-GEF  files,  ASCII  ARC  Ungenerate  files,  ASCII  DXF  files,  and  ASCII  vector  files  into 
binary  vector  files.  It  also  creates  support  files,  the  dig_plus  file  and  the  dig_att  file  (only  created  when 
importing  DLG,  SCS-GEF,  or  ARC  files).  The  dig_plus  file  contains  topological  information  obtained 
by  analyzing  the  vector  file.  The  dig_att  file  contains  attribute  information  ’stripped’  from  the  DLG  file 
or  SCS-GEF  text  data.  This  dig_att  file  is  created  for  vector  files  by  the  labeling  function  of  the 
GRASS  v. digit  program. 

IMPORT  FILES 

After  enteriiig  the  command  v .import,  the  user  will  be  asked  which  type  of  file  to  import  and  create 
support  files  for: 

Import  to  GRASS  Vector  Format  and  Creates  Needed  Support  Files 

1  -  ASCII  DLG  file  to  GRASS  Vector  Format 

2  -  Binary  DLG  file  to  GRASS  Vector  Format 

3  -  ASCII  DIGIT  file  to  GRASS  Vector  Format 

4  -  Binary  DIGIT  file  to  GRASS  Vector  Format 

5  -  ASCII  SCS-GEF  file  to  GRASS  Vector  Format 

6  -  ASCII  ARC/INFO  file  to  GRASS  Vector  Format 

7  -  ASCII  DXF  file  to  GRASS  Vector  Format 

8  -  ASCII  TIGER  file  to  GRASS  Vector  Format 

If  numbers  1-3  or  5-8  are  chosen,  vimporl  will  respond  with  the  current  data  base  units  (in 
feet  or  meters),  and  ask  if  the  new  vector  file  is  in  the  correct  units  for  the  data  base  location. 

If  the  new  vector  file  is  not  in  the  conect  units,  vimport  will  not  allow  it  to  be  placed  in  the 

current  data  base  location.  For  each  data  base  location,  all  data  layers  should  have  the  same 
units.  If,  for  some  reason,  a  data  layer  has  different  units  than  the  rest  of  the  data  layers  in  the 
same  data  base,  a  new  data  base  location  will  have  to  be  created  for  it. 

ASCII  DLG  File  to  GRASS  Vector 

Converts  ASCII  DIG  files  (such  as  those  created  in  GRASS)  to  a  vector  file  and  creates  the  dig_plus 
and  dig_att  support  files.  The  user  is  asked  several  questions: 

1 .  The  name  of  the  DLG  data  file. 

NOTE:  It  should  be  available  in  the  SLOCATION/dlg  directory.  If  the  DLG  data  has  an 
attribute  flat  file,  it  should  also  be  in  SLOCAIlON/dlg. 

2.  Determine  if  this  map  is  composed  of  Aea  or  Line  information. 

NOTTi  Some  machine-processed  DIXj  files  do  not  make  tlx;  distinction  between  lines  and  area 
edges.  For  example,  in  a  roads  map,  where  the  desired  information  is  line  data,  a  downtown 
Nock  surrounded  by  roads  may  be  processed  as  an  area.  Because  of  this,  the  user  is  asked  to 
choose  whether  to  give  precedence  to  areas  or  lines.  If  precedence  is  given  to  lines,  the  user 
should  be  aware  that  any  lines  that  bound  unlabclcd  areas  in  the  DLG  file  will  be  stored  as  line 
data.  Any  unlabeled  areas  would  therefore  be  lost  (this  is  only  a  concern  when  areas  are 
unlabelcd,  labeled  area  information  will  be  retained).  If  precedence  is  given  to  areas,  lines  w  ill 
be  stored  as  boundaries  to  areas  that  are  unlatxled. 

3.  Determine  if  you  want  to  snap  nodes  to  other  nodes  within  a  threshold. 

NOTE):  BE  CAREFUL!!!  litis  threshold  is  calculated  using  the  scale  of  the  original  DIG  or 


GRASS  4.0  (Summer  1991) 


US.  An nv  CTRL 


478 


v.import 


GRASS  Reference  Manual 


v.import 


v. digit  file.  If  the  threshold  is  too  high,  excessive  snapping  may  occur,  destroying  the  file.  In 
general,  users  seldom  need  to  snap  nodes.  If  snapping  of  nodes  is  desired,  the  user  may  want 
to  run  v. support  separately,  v support  allows  the  user  to  set  the  snapping  threshold. 

4.  Does  the  DI  X)  data  contain  GRASS  category  codes? 

NO  11'.:  Most  non- GRASS  computer  systems  will  not  be  able  to  provide  the  necessary  codes. 
Ihc  fiat  attribute  lile  serves  this  purpose.  If  the  answer  to  this  question  is  NO 

1)  I  nter  a  SUBJECT  MA1TER  file  name. 

A  subject  file  will  be  used  to  assign  GRASS  category  codes  to  the  DUG  data.  It  is  structured 
the  s;une  as  a  dig_cats  category'  file.  It  is  suggested  that  a  SUBJ  directory  Ire  created  in  the 
GRASS  location  and  a  file  containing  all  Dl/i  attribute  text  labels  by  category'  be  created. 
Thi  s  will  lie  required  to  provide  consistency  across  several  maps  (quads)  within  one  location. 
Ihc  user  may  use  the  vi  text  alitor  or  the  SCS  macro  make_subject  to  create  it. 

2)  Enter  an  ATERIBUfl:  file  name. 

'ihis  is  the  name  of  the  flat  file  which  will  accompany  a  DUG  from  a  non- GRASS  system. 
Ihis  file  contains  all  of  the  DIjG  area  numbers  with  a  corresponding  text  label. 

3)  Is  the  DI.G  data  from  an  ARC/INK)  system? 

ARC/INf  X)  DI.G  data  is  handled  in  a  slightly  different  manner. 

4)  Does  'Ihe  DI  G  contain  a  Universe  Polygon? 

Some  DIXj  files  may  or  may  NOT  have  this  and  processing  will  be  required  to  handle  each 
case  differently. 

’Ihis  process  is  done  in  three  phases: 

1.  If  the  DIXj  does  NO  I  contain  category  codes,  then  a  category  file  from  the  attribute  file  is 
created.  Then  the  ASCII  dig  file  is  converted  to  a  binary  dig  file. 

OR 

If  the  DIXj  does  contain  category  codes,  then  the  ASCII  DLG  file  is  ainverted  to  a  binary' 
DI  G  file. 

2.  'Ihc  binary  dig  file  is  converted  to  a  binary  vector  file,  and  the  dig_att  support  file 
containing  attribute  infonnation  is  created. 

3.  Ihe  dig  plus  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 

Binary  DI.G  File  to  GRASS  Vector 

Converts  binary  DIXj  files  (which  should  be  in  the  bdlg  directory)  to  a  vector  file  and  creates  the 
dig_plus  arul  dig_alt  support  files.  The  user  is  asked  whether  precedence  should  Ire  given  to  Areas  or 
lines  and  if  ntxles  should  be  snapped  to  other  nodes  within  a  calculated  threshold. 

Ihis  process  is  done  in  two  pi  rases: 

1 .  Ihe  binary  DIXj  (bdlg)  file  is  converted  to  a  binary  vector  file,  and  the  dig_att  support  file 
containing  attribute  information  is  created. 

2.  Ihe  dig_plus  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 

ASCII  Vector  File  into  GRASS  Vector 

Converts  ASCII  v. digit  files  (which  are  located  in  dig  ascii  directory)  into  binaiy  vector  files  and 
creates  the  dig  plus  support  file.  Since  a  vector  file  keeps  the  distinction  lx- tween  lines  and  area  edges, 
the  user  is  not  asked  to  give  precedence  to  cither.  However,  the  user  will  be  asked  if  the  user  wants  to 
snap  from  ntxles  to  other  axles  within  a  calculated  threshold. 

Ihis  pnxess  is  done  in  two  pliases. 

1.  Ihe  ASCII  vector  file  is  converted  to  a  binary  vator  file,  ami  the  dig  plus  support  file  is 
created. 

2.  Ihe  dig  plus  support  lile  is  created  by  analyzing  the  vector  file  for  topological  information. 
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Binary  Vector  File  to  GRASS  Vector 

Geates  the  dig _p lus  support  file. 

This  process  is  done  in  one  phase: 

1.  The  dig_plus  support  file  is  created  by  analyzing  the  vector  file  for  topological  information. 

ASCII  SCS-GEF  File  to  GRASS  Vector 

Geates  the  dig_plus,  dig_att,  and  dig_cats  support  files.  Geates  a  registration  coordinates  file. 

Allows  a  user  to  create  a  GRASS  vector  file  from  a  SCS-GEF  format  ASCII  file. 

1.  The  program  will  first  request  the  name  of  the  SCS-GEF  file  to  be  read  in;  it  expects  to  find 
the  data  in  the  SLOCAITON/gef  directory. 

2.  The  program  will  then  request  the  name  of  a  GRASS  vector  file. 

3.  The  program  will  then  request  the  name  of  a  SUBJECT  file.  A  subject  file  will  be  used  to 
assign  GRASS  category  codes  to  the  SCS-GEF  data.  It  is  structured  the  same  as  a  dig_cats 
category  file.  It  is  suggested  that  a  SUBJ  directory  be  created  in  the  GRASS  location  and  a 
file  containing  all  SCS-GEF  text  labels  by  category  be  created.  This  will  be  required  to 
provide  consistency  across  several  mapsets  (quads)  within  one  location.  The  user  may  use  the 
vi  text  editor  or  the  SCS  macro  make_subject  to  create  it. 

4.  The  program  will  then  read  the  SCS-GEF  header  information,  interactively  present 
information  that  was  available,  and  request  additional  data  of  the  user.  These  questions  are: 

Name  of  their  organization,  (from  SCS-GEF) 

Digitized  Date.  (from  SCS-GEF) 

Map  Name.  (from  SCS-GEF) 

Map  Location.  (from  SCS-GEF) 

Other  Information.  (from  SCS-GEF) 

State  FIPS  code. 

County  FIPS  code. 

Present  GEF  Coord.  System  (table,  stplane,  11,  utm). 

Coord.  System  Desired  (utm,  stplane,  11,  albers). 

The  program  will  then  actively  read  the  SCS-GEF  data  file  and  process  it. 

Note:  scripts  contains  SCS  macro  make_l_gef.  This  macro  makes  one  file  out  of  the  three  (3) 
files  found  in  SCS-GEF  (see  SCS-GEF  technical  specifications  for  more  information).  The 
macro  must  be  run  on  each  data  set  BEFORE  vdmport. 

ASCII  ARC/INFO  Ungenerate  Format  Files  to  GRASS  Vector  Format 

Geates  the  dig_plus,  dig_att,  and  chg_cats  support  files. 

The  program  will  prompt  you  to  enter  the  names  of  ARC/INFO  files  to  be  imported  to  GRASS. 
ARC/INFO  vector  files  to  be  imported  into  GRASS  must  be  exported  from  ARC/INFO  using  the 
ARC/INFO  Ungenerate  command.  ARC/INFO  vector  files  which  are  to  be  imported  to  GRASS,  must 
be  either  line  or  polygon  coverages.  They  must  also  be  placed  in  a  SLOCATION/arc  directory.  The 
section  of  the  ARC/INFO  manual  that  covers  the  Ungenerate  command  describes  how  to  export  line 
and  polygon  coverages. 

A  polygon  coverage  is  represented  by  three  files: 

1)  a  lines  file,  which  contains  coordinates  of  all  the  area  ec^e  lines; 

2)  label-point  file,  which  contains  coordinates  of  label-points  each  with  a  unique  label-point  ID 
number.  There  is  one  label-point  for  each  polygon  defined  in  the  lines  file;  and 

3)  a  label-text  file,  which  associates  label-punt  ID  number  with  a  category  value  and  attribute 
text. 
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A  line  coverage  is  represented  by  two  files: 

1)  a  lines  file,  which  contains  coordinates  of  file  lines,  each  with  a  line- ID  number;  and 

2)  a  label-text  file,  which  associates  each  line- ID  number  with  a  category  value  and  attribute 
text. 

The  program  will  start  out  by  asking  you  which  type  of  coverage  is  to  be  imported,  as  follows: 

IMPORTING  A  POLYGON  OOVFRAGE 

The  prompts  that  will  be  presented  for  coverage  type  "polygon." 

COVERAGE  TYPE 
Filter  "polygon"  or  "line" 

Hit  RETURN  to  cancel  request 

> 

Answer  "polygon" 

NEATIJNE 

Do  you  want  a  neatline  ? 

Filter  "yes"  or  "no" 

> 

If  you  answer  yes  then  vectors  representing 
a  box  around  the  data  will  be  inserted  into 
the  resulting  GRASS  vector  file,  otherwise 
no  neatline  will  be  created. 

Next  the  program  will  prompt  for  the  name  of  the  lines-file  containing  the  arc  coordinates  of  the 
polygons.  The  lines-file  is  created  with  the  Ungenerate  IJNES  option  and  is  the  same  format  as  tlie 
map_name.pol  file  created  by  the  program.  The  following  is  the  prompt: 

LINES  HIT  NAME 

Filter  name  of  the  file  created  with  the  IJNES 
option  of  the  ARC/INFO  Ungencrate  command. 

IDt  RETURN  to  cancel  request 

> 

The  next  prompt  for  coverage  type  "polygon"  asks  for  the  name  of  the  label-points  file.  The  label- 
points  files  is  created  with  tire  Ungenerate  POIN1S  option  and  is  the  same  format  as  the 
mapname.lab  file  created  by  the  export. vect  ARC  program.  The  following  is  the  prompt: 

LABEL- ITHNTS  FIN-NAME 
Enter  name  of  file  created  with  the  POINTS 
option  of  the  ARC/INF'O  Ungenerate  command. 

Hit  RETURN  if  there  is  no  such  file 

> 

The  last  prompt  for  coverage  type  "polygon"  asks  for  the  name  of  the  la  el-text  file.  This  file 
associates  each  label-point  ID  number  with  a  text  string  and  is  the  same  format  as  the  mapname.txt  file 
created  by  the  export. vect  ARC  program.  The  following  is  the  prompt: 

LABEL-TENT  FILENAME 
litter  the  name  of  a  file  that  assrxiates 
label-point  II)  numbers  with  text  label  strings 
1  fit  RETURN  if  there  is  no  such  file 

> 

The  program  will  then  scan  the  label  text  file  to  determine  how  many  columns  are  in  the  file  and  to 
detenninc  which  coliunn  shtxikl  lie  used  as  the  latxljxiint  ID  in  uni  ter  column.  The  program  will  then 
tell  yrxi  how  many  lines  and  coliunns  ;ire  in  the  label-text  file.  Next  you  will  lx  prompted  to  enter  the 
number  of  the  column  to  lx  used  for  GRASS  category  values.  The  category  number  column  MUST 
contain  only  integers. 
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Enter  the  number  of  the  column  that  is  to  be  used 
for  GRASS  category  values: 

and  the  number  the  column  to  be  used  for  GRASS  attribute  text.  The  attribute  text  column  can  contain 
a  floating  point  number,  an  integer,  or  a  word. 

Enter  the  number  of  the  column  that  should  be  used 
for  GR  .SS  attribute  text: 

Once  you  enter  the  category  and  attribute  column  numbers,  the  program  will  begin  conversion  of  the 
ARGTNFO  Ungenerate  files  into  GRASS  vector  format. 

IMPORTING  A  LINE  COVERAGE 

Rrst,  you  are  prompted  for  the  name  of  the  lines-file  containing  the  arc  coordinates  of  the  lines.  The 
lines-file  is  created  with  the  Ungenerate  LINES  option  and  is  the  same  format  as  the  mapname.lin  file 
created  by  the  export. vect  ARC  program. 

LINES  FILENAME 

Enter  name  of  the  file  created  with  the  lines 
optical  of  the  ARC/INFO  Ungenerate  command. 

Ifit  RETURN  to  cancel  request 

> 

The  last  prompt  for  coverage  type  "line"  asks  for  the  name  of  the  label-text  file.  This  file  associates 
each  line-ID  number  with  a  text  string  and  is  the  same  format  as  the  mapname.txt  file  created  by  the 
export. vect  ARC  program. 

LABEL-TEXT  FILENAMES 
Fnter  name  of  file  associating  line  ID  numbers 
with  label  text. 

Hit  RETURN  if  there  is  no  such  file 

> 

The  program  will  scan  the  label-text  file  to  detenr:ne  how  many  columns  are  in  the  file  and  will  then 
tell  you  how  many  columns  are  in  the  label-text.  Next  you  will  be  prompted  to  alter  the  number  erf  the 
column  to  be  used  for  line-ID  numbers. 

Enter  the  number  of  the  column  that  is  to  be  used 
for  line-ID  ntunbers: 

Next  you  will  be  prompted  to  enter  ti»e  number  erf  the  column  to  be  used  for  GRASS  category'  values. 
The  category  number  column  MUST  contain  only  integers. 

Enter  the  number  of  the  column  that  is  to  be  used 
for  GRASS  category'  values: 

and  the  number  of  the  column  to  be  used  for  GRASS  attribute  text.  The  attribute  text  column  can 
contain  a  floating  point  number,  an  integer,  or  a  word. 

Enter  the  number  of  the  column  that  should  be  used 
for  GRASS  attribute  text: 

Once  you  enter  the  column  numbers,  the  program  will  begin  conversion  of  the  ARC/INFO  Ungenerate 
files  into  GRASS  vector  format. 

DATA  FILE  FORMATS 

Following  are  examples  of  the  data  files  discussed  in  the  section  above. 

LINES  FILE,  also  known  as  xxx.lin  or  xxx.pol  file.  This  type  of  file  can  be  created  m 
ARC/INFO  by  using  the  lines  subcommand  of  the  Ungenerate  command.  Each  line,  or  arc, 
is  defined  by  a  line-ID  number,  followed  by  a  list  of  at  least  two  casting  and  northing 
coordinate  pairs,  followed  by  a  line  with  the  word  "END’.  The  file  is  terminated  with  the 
word  "END' . 


4S2 


GRASS  4.0  (Summer  1991) 


U  S.  Army  (ERL 


v. import 


GRASS  Reference  Manual 


v. impart 


The  line-ID  number  is  only  important  for  line  coverages.  For  a  line  coverage,  the  line- ID 
number  is  the  number  that  associates  each  line  with  its  attribute  data. 

3 

711916.000000  4651803.000000 

711351.875000  4651786000000 
END 

3 

709562500000  4651731000000 
709617250000  4651624000000 
709617250000  4651567000000 
709585.000000  4651503000000 

709601.125000  4651470.000000 

709696.875000  4651503.000000 
709720500000  4651574000000 
709823.750000  4651575.000000 

709893.125000  4651741.000000 
END 

3 

710296.875000  4651491.000000 

710295.125000  4651470.000000 
710223.000000  4651454.000000 
710154500000  4651463.000000 

END 

END 

I  Alt  El,  KENT'S  FILE,  also  known  as  xxxJab  file.  This  type  of  file  can  be  created  in 
ARC/TNFO  by  using  the  Points  subcommand  of  the  Ungenerate  command.  The  first  number 
on  each  line  is  a  label-point  ID  number,  the  following  two  are  easting  northing  coordinates  for 
the  label-point. 

1  711539.875000  4651743.000000 

2  711429.000000  4650632.000000 

3  711027.625000  4651736.000000 

4  711022.625000  4651519.000000 

5  710482.750000  4651494.000000 

6  710474  500000  4651667.000000 

7  709269.750000  4651018.000000 

8  709726500000  4651604.000000 

9  708926375000  4651195.000000 

10  708567500000  4651644.000000 

11  708272.750000  4651407.000000 
END 

LABEL-TEXT  FILE,  also  known  as  xxx.txt  file.  This  type  of  file  can  be  created  in 
ARC/INFO  by  using  the  Display  command. 
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11  65,802.688  1,575.088  11  10  16  3 

NOTES 

When  importing  a  polygon  coverage,  the  program  finds  the  label-point  ID  in  a  label-text  file  by  looking 
for  the  second  column  in  the  file  that  contains  a  ”1"  on  line  1,  and  a  ”2"  on  line  2. 

If  you  are  missing  a  label-points  or  a  label-text  file  you  can  still  import  ARC/INPO  data  (but  none  of 
your  lines  or  areas  will  be  labeled). 

ASCII  DXF  Format  Files  to  GRASS  Vector 

Geates  the  dtg_plus,  dig^att ,  and  dig_cats  support  files. 

ASCII  TIGER  Format  Files  to  GRASS  Vector 

This  program  imports  Census  line  features  from  TIGER  records  typel  and  type2  into  GRASS  vector 
format.  Both  pre- Census  and  post-Census  data  formats  can  be  used.  Specific  Census  Feature  Gass 
Codes  ((TOC)  can  be  extracted  completely  or  in  various  combinations.  These  codes  are  described  in 
the  HGER/line  Census  Hies  1990  documentation  available  from  the  Bureau  of  the  Census.  Ai 
additional  feature  code  consisting  erf  the  three  letters  "BOLT'  may  also  be  specified  to  extract  a  county 
boundary.  Condensed  Record  1  files  may  be  imported  with  the  -c  flag.  These  files  should  be  identified 
with  a  trailing  "x"  character  on  the  filename. 

The  TIGER  files  must  be  in  sorted  order  before  being  used.  This  can  be  done  by  using  the  following 
command: 

sort  TGR12113JF21  -o  tl2113.1 
sort  TGR12113.F22  -o  U21132 

For  consistency,  the  sorted  file  should  be  written  as  above.  It  should  consist  of  a  Y  followed  by  the 
State  and  County  FIPS  code,  then  a  ’ .’  and  then  a  value  to  identify  the  record  number. 

SEE  ALSO 

vjn.dlgjcs,  v.in.dlg,  v.in.ascii,  v.in.arc,  v.in.dxf,  vJn.tigerjcs 

AUTHOR 

R.  L.  Germ,  USDA  SCS,  NHQ-OGIS 
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NAME 

v.in.dlgjcs  -  Developed  to  handle  DLG-3  ASCII  import  of  data,  specifically  a  DLG  WITHOUT 
category/anribute  codes.  DLG  files  with  this  affliction  will  require  a  flat  ASCII  file  having  a  1  to  1 
correspondence  between  DLG  area  number  and  a  text  label. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

vjn.dlg.scs 
v  Jn.dlg.scs  help 

vjn.dlg.scs  [-uf]  [dig  =name)  [bdlg=name]  [att=name] 

DESCRIPTION 

Under  normal  circumstances,  the  v  An. dig  program  will  handle  the  requirements  of  reading  DLG  data 
and  creating  vector  maps  from  it.  However,  v. in. dig  assumes  that  the  DLG-s  file  will  contain 
major/mi nor  category  numbers;  this  is  NOT  always  the  case.  In  some  instances,  the  user  may  want 
label  names  with  the  I>LG  data;  the  current  DDG-3  specification  does  not  provide  that.  SCS  has 
developed  this  program  to  meet  that  need. 

Notes: 

Ibis  pregram  is  normally  NOT  called  from  the  command  line.  v  .import  will  create  the 
command  string,  then  execute  it. 

Ibis  program  converts  an  ASCII  DLG  file  to  a  binary  DLG  file  with  attribute  codes  in  the 
major  minor  fields,  and  creates  a  dig_cats  file  with  the  correct  code/label  correspondence.  The 
pregram  v.a.b.dlg  must  be  ran  after  this  pregram  to  create  the  GRASS  vector  files. 

It  is  assumed  that  the  DLG  data  file  contains  only  one  set  of  geographic  information;  i.e., 
areas,  err  lines,  or  points.  This  pregram  WIL1  FAIT,  if  mixed  data  is  encountered. 

Degenerate  lines  are  accepted  in  this  program  as  point  data. 

IX  Xiall  File  format 

Ibe  DIXi.aU  attribute  file  format  is  simple: 


field  1  - 
field  2  - 

DlXi  [arca|fincfcx>int]  number 

1  nbel 

COMMAND  LINK  OPTIONS 

Flags: 

-u 

IX  G  file  contains  universe  area. 

-f 

An  attribute  file  is  included. 

Parameters: 

dig  name 

ASCII  D1  Xi  (dig)  tile  name. 

bdlg  name 

Binary  IX jG  (bdlg)  file  name. 

att  name 

IX  G  attribute  ( dig. att )  tile  n;unc 

SEE  ALSO 

v. digit,  v.import,  v.tn.dlg 

AUTHORS 

R  L.  Glenn.  LJSDA  SCS.  NIKX’GIS 
T.  W.  Carlson,  USDA.  SCS.  NIKX  GIS 
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NAME 

vjnscsgef  -  Converts  SCS  Geographic  Exchange  Format  (SCS-GEF)  ASCII  data  into  a  GRASS  vector 
file. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

vJn.scsgef 
v  Jn.scsgef  help 

v-in-scagef  [-o]  [gtf=name]  [output  =nome]  [cat=name] 

DESCRIPTION 

v.in.scsgef  allows  a  user  to  create  a  GRASS  vector  file  from  a  SCS-GEF  format  ASCII  file. 

1.  The  program  will  first  request  the  name  of  the  SCS-GEF  file  to  be  read  in;  it  expects  to  find 
the  data  in  the  current  directory.  It  is  suggested  to  create  a  gef  directory  and  put  all  SCS-GEF 
data  tnere. 


2.  The  program  will  then  request  the  name  of  a  GRASS  vector  file. 

3.  The  program  will  then  request  the  name  of  a  SUBJECT  file.  A  subject  file  will  be  used  to 
assign  GRASS  category  codes  to  the  SCS-GEF  data.  It  is  structured  the  same  as  a  dig_cats 
category  file.  It  is  suggested  that  a  SUBJ  directory  be  created  in  the  GRASS  location  and  a 
file  containing  all  SCS-GEF  text  labels  by  category  be  created.  This  will  be  required  to 
provide  consistency  across  several  maps  (quads)  within  one  location.  The  user  may  use  the  vi 
text  editor  or  the  SCS  macro  make _subject  to  create  it. 

4.  The  program  will  then  read  the  SCSGEF  header  information,  interactively  present 
information  that  was  available,  and  request  additional  data  of  the  user.  These  questions  are: 
Name  of  their  organization,  (from  SCS-GEF) 

Digitized  Date.  (from  SCS-GEF) 

Map  Name.  (from  SCS-GEF) 

Map  Location.  (from  SCS-GEF) 

Other  Information.  (from  SCS-GEF) 

State  FIPS  code. 

County  FIPS  code. 

Present  GEF  Coord.  System  (table,  stplane,  11,  utm). 

Coordinate  System  Desired  (utm,  stplane,  II,  albers). 

The  program  will  then  actively  read  the  SCS-GEF  data  file  and  process  it. 

scripts  contains  SCS  macro  make_l_gef.  This  macro  makes  one  file  out  of  the  three  (3)  files  found  in 
SCS-GEF  (see  SCS-GEF  technical  specifications  for  more  information).  The  macro  must  be  mn  on 
each  data  set  BEFORE  v.irucs.gef. 

COMMAND  LINE  OPTIONS 
Flag: 

-<» 

Parameters: 


The  SCS-GEF  is  in  the  OLD  format  (24  ciiar). 


gef ^=name  ASCII  SCS-GEF  file  name, 

output  =  siame  Vector  file  name, 

cat  =name  Category  file  name. 

SEE  ALSO 

make_l_gef,  make_subject,  v.import 

AUTHOR 

R.  L.  Glenn,  USDA  SCS,  NHQ-CGIS 
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NAME 

v.in.tigerjcs  -  Converts  ASCII  TIGER  data  files  from  the  U.S.  Dept,  of  Commerce  Bureau  of  the 
Census. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.in.tiger.scs 
vun.tiger.scs  help 

vJn.tiger.scs  [-cv]  tigl  =name  tig2  =name  out  =name  cfc=name[/iame ,...] 

DESCRIPTION 

Jhis  program  imports  Census  line  features  from  TIGER  records  typel  and  type2  into  GRASS  vector 
format.  Both  pre- Census  and  post-Census  data  formats  can  be  used.  Specific  Census  Feature  Class 
Codes  (CFOC)  can  be  extracted  completely  or  in  various  combinations.  These  codes  are  described  in 
the  IlGERyline  Census  Files  1990  documentation  available  from  the  Bureau  of  the  Census.  An 
additional  feature  code  consisting  of  the  three  letters  ”BO(J'  may  also  be  specified  to  extract  a  county 
boundary.  Condensed  Record  1  files  may  be  imported  with  the  -c  flag.  These  files  should  be  identified 
with  a  trailing  "x"  character  on  the  filename. 


COMMAND  LINE  OPTIONS 
Flags: 

-c  Condensed  TIGER  file, 

-v  Verbose  output. 


Parameters: 
tigl  =name 
tig2=name 
out  name 


TIGER  file  1. 

TIGER  file  2. 

New  vector  file  name. 


cfc  name, name,...  Specific  Census  Feature  Gass  (CFCC)  codes. 

EXAMPLE 

To  extract  all  Primary  (Al)  and  Secondary  (A2)  roads  from  a  county’s  TIGER,  files  the  following 
command  would  be  used: 


van. tiger .scs  tigl=312113.1  tig2=tl2113.2  aut=roads  cfc=Al,A2 
To  extract  all  the  Hydrographic  features  in  a  county  ’s  TIGER  files  with  verbose  output: 

vJn.tiger.scs  -v  tigl=*12113.1  tig2=tl2113.2  out^iydro  cfc=fl 
To  extract  the  county  boundary  the  command  would  be: 

vJn.tiger.scs  tigl^l2113.1  tig2=tl2113.2  out=4>ou  cfc=*OU 

NOTES 

The  TIGER  files  must  be  in  sorted  order  before  being  used.  This  can  be  done  by  using  the  following 
command: 


sort  TGR12113.F2I  -o  1 121 13.1  sort  TGR12113.F22  -®  1 121 13.2 

For  consistency  the  sorted  file  should  be  written  as  above.  It  should  consist  of  a  ’f  followed  by  the 
State  and  Cotinty  FIPS  code,  then  a  ’ .’  and  then  a  value  to  identify  the  record  number. 

The  CICC  code  ’BOLT  used  to  extract  the  County  Boundary  should  be  used  alone  as  it  will  result  in  a 
polygon  ARFA  being  created. 

Qirrently  output  is  in  UTM  only. 
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SEE  ALSO 

v  import 

AUTHOR 

Paul  H.  Rikuhara,  USDA  SCS  National  Cartographic  Center 
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NAME 

vjnakejubj  -  Oeate  a  "subject"  file  from  all  category  labels  found  in  a  set  of  listed  vector  maps. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.make-subj 
v  anake-subj  help 

vjnake^ubj  map=name[/iame,...]  subj  =name 
DESCRIPTION 

Program  to  read  the  dig_cals  file  for  each  listed  map.  The  program  then  creates  (or  appends  to,  if  the 
SUBJ  file  exists)  a  "subject"  file  of  all  of  the  labels,  giving  a  unique  category  value  to  each. 

This  prt^ram  was  designed  to  create  a  common  category  file  from  maps  of  areas  that  have  the  same 
category  labels,  but  different  category’  values;  and  that  mast  be  joined/merged  together. 

COMMAND  LINE  OPTIONS 
Parameters: 

map  =name  Vector  map-  source  for  composite. 

subj  =rtame  New  SUBJ  file  name. 

SEE  ALSO 

v. merge 

AUTHOR 

R.  L.  Glenn,  USDA  SCS,  NJJOCXHS 


GRASS  1.0  (Summer  |0‘)|  ) 
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NAME 

vjnerge  -  Merges  vector  map  files. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

▼.merge 
▼.merge  help 

▼.merge  [-mr]  map  =name[jtame,...]  autput=name  subj  -name 
DESCRIPTION 

Program  to  read  the  dig_caJ$  file  for  each  named  map.  The  program  then  compares  the  category  label 
(NOT  the  value)  to  the  labels  in  the  named  subject  file.  If  the  label  is  found  in  the  subject  file,  the 
corresponding  attribute  values  of  the  map  are  changed  to  the  subject  file  category  value.  When  all 
maps  are  completed  a  patch  operation  is  performed. 

This  program  was  designed  to  merge  maps  for  areas  that  have  the  same  category  labels,  but  different 
category  values  associated  with  those  labels. 

There  are  two  flags  for  v. merge. 

Flag* 

-m 


-▼ 

Parameters: 

map=name,name,... 
output  =name 
subj  name 

NOTES 

The  program  vjnake.subj  can  be  mn  prior  to  using  v.merge.  v.makejubj  will  read  the  category 
labels  of  each  map  in  its  list  and  create  a  subject  file  of  laliels  and  values.  Users  may  opt  to  create  the 
subject  file  by  other  means  if  they  wish. 

v.rmedge  must  be  mn  on  any  mapscts  in  the  v.merge  list  prior  to  issuing  the  v.merge  command. 
Common  edges  will  need  to  be  removed  prior  to  the  v.merge  operation. 

SEE  ALSO 

v.makesubj,  v.rmedge 

AUTHOR 

R.  L.  Qenn,  USDA  SCS,  NHOCGIS 


Use  RAM  to  hold  subject  file  category  values.  This  may  be  faster  than  the 
default  (use  of  disc  files);  however,  memory  may  not  be  laige  enough  for  all 
of  the  subject  file. 

By  default,  ally  the  name  of  the  mapset  processing  is  sent  to  standard 
output.  In  verbose  mode,  the  user  is  given  additional  information  on 
program  operations. 

Vector  map-sairce  for  composite. 

New  name  assigned  to  vector  composite  map. 

SUBJ  file  name. 
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NAME 

v. out. dlg^cs  -  Converts  binary  GRASS  vector  data  to  binary  DLG-3  Optional  vector  data  format. 

(SCS  GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out.dlg.scs 
v.out.dlg.scs  help 

v.out.dlg.scs  input  name  output  name 
DESCRIPTION 

The  GRASS  program  v. out. dlg^cs  allows  the  user  to  conv  ert  GRASS  vector  data  to  DLG-3  Optional 
format,  for  export  to  other  systems,  just  as  v.outxUg  does.  However,  a  flat  ASCII  file  of  labels  and 
their  corresponding  dig  record  numbers  is  created.  This  flat  file  is  used  to  provide  the  label  information 
to  other  sy  stems,  since  most  do  NOT  support  text  attributes  in  a  DLG  import. 

The  user  can  run  the  program  non-interactively  by  specifying  all  program  arguments  on  the  command 
fine,  in  the  form: 

v.out.dlg.scs  input  =name  output  ==name 


Parameters: 

input  name  Name  of  the  binary  GRASS  vector  data  file  to  be  converted  to  DLG-3  format. 

output  =name  Name  to  be  assigned  to  the  DIG- 3  Optional  format  output  file  created. 

If  the  user  does  not  give  the  names  of  an  input  and  output  file  on  the  command  fine,  the  program  will 
prompt  the  user  to  enter  these  names. 

NOTES 

The  v.out.dlg.scs  program  requires  that  the  input  vector  map  layer  have  full  topological  information 
associated  with  it.  This  means  that  the  GRASS  program  v.. support  should  have  been  the  last  program 
to  have  effected  ;uiy  changes  upon  the  vector  map  layer  before  it  is  tun  through  v.out.dlg.scs.  If  this  is 
not  the  case,  v.out.dlg.scs  will  terminate  with  a  message  that  v. support  needs  to  lie  run. 

llie  output  from  v.out.dlg.scs  will  be  placed  in  $!/)(' All ON/dlg .  The  output  flat  lile  from 
v.out.dlg.scs  will  also  lie  placer!  in  $ lDCATlONIdlg ,  with  the  extension  ”.atl”  attached  to  the  same 
output  name. 

SEE  ALSO 

v.import,  v.in.ascii,  v.in.dlg,  v.in.dlg.scs,  v.support 

AUTHOR 

R  I..  Glenn,  USDA  SCS,  NHQ-CGIS 
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NAME 

vxjutjcsgef  -  Converts  binary  GRASS  vector  data  to  ASCII  SCS-GEF  vector  data  format. 

(SCS  GRASS  Vector  Data  Export  Program) 

SYNOPSIS 

v.out.scagef 
v.out  jjcsgrf  help 

r.out^csgrf  input  =name  output  =name 
DESCRIPTION 

The  GRASS  program  v.outscsgef  allows  the  user  to  convert  GRASS  vector  data  to  SCS-GEF  format, 
for  export  to  other  systems. 

v.out.scsgef  creates  the  SCS-GEF  header,  lines,  text,  and  feature  files.  All  files  are  created  and  placed 
in  a  $LOCATION/gef  directory  as  a  single  UNIX  file  under  the  output  name. 

The  following  is  the  SCS-GEF'  file  structure: 

header  record  1 

I  I 

header  record  n 
-head 

line  record  1 

I  I 

line  record  n 
-line 

text  record  1 

I  I 

text  record  n 
-text 

feature  record  1 

I  I 

feature  record  n 
-feat 

The  user  will  be  required  to  use  standard  UNIX  commands  to  separate  this  file  into  individual  files  as 
required  by  SCS-GEF  specifications. 

Ihe  user  can  nut  the  program  non-interactively  by  specifying  all  program  arguments  on  the  command 
line,  in  the  fomi: 

v.out.scsgef  input  name  output -name 


Parameters: 

input  name  Name  of  the  binary  GRASS  vector  data  file  to  lx:  converted  to  SCS  ( il  l  '  formal, 

output  =name  Name  to  be  assigned  to  the  SCS  GEE  output  file  created. 

If  the  user  d<x-s  not  give  the  names  of  an  input  and  <xitput  file  on  the  command  line,  the  program  will 
prompt  the  user  to  enter  these  names. 

NOTES 

Ihe  v.out.scsgef  program  requires  that  the  input  vector  map  layer  have  lull  topological  information 
assix'iatcd  with  it.  Iliis  means  that  the  GRASS  program  v. support  should  have  I  veil  the  last  program 
to  have  effected  any  changes  ti|xm  the  vector  map  layer  Ixdore  it  is  mil  through  v.out.scsgef.  If  this  is 
not  the  case,  v.out.scsgef  w  ill  terminate  with  a  message  that  v.support  needs  to  lx  nin. 

SEE  ALSO 

v.cxport,  v. import,  v. out  ascii,  v.out.dlg,  v. out. dig. sc s,  v.support 
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AUTHOR 

R  L.  Glenn,  USDA  SCS,  NHQ-CXHS 
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NAME 

v.proj  -  Allows  projection  conversion  of  vector  files. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.proj 
v.proj  help 

DESCRIPTION 

v.proj  allows  a  user  to  create  a  new  vector  map  in  another  mapset  with  a  different  projection,  from  an 
existing  vector  map  in  the  current  or  some  other  user- specified  mapset. 

Note:  If  the  "outset"  mapset  is  not  available,  v.proj  will  create  it  in  the  current  location.  If  the 
"outset"  mapset  exists,  v.proj  reads  its  projection  information,  and  uses  it  to  convert  to  the  output 
projection. 

If  the  "outset"  projection  information  is  not  available,  v.proj  mns  the  program  msetproj  to  create  it. 

EXAMPLE 

The  current  mapset  (Map_utml4)  has  a  utm  projection,  the  coordinates  are  for  zonel4  meters,  and 
contains  the  map  sample.  The  user  wants  to  create  a  new  map  of  sample  in  the  mapset  lambert 
(which  is  a  Lambert  Conformal  Conic  projection  mapset). 

The  command: 

v.proj  map  .sample  outset  =lambert 

will  create  a  new  map  sample  in  the  mapset  lambert,  changing  the  utm  coordinates  of  sample  into 
lambert  coordinates.  If  the  mapset  lambert  did  not  exist,  v.proj  would  have  created  it. 
v.proj  will  create  dig,  dig_att,  and  dig_cats  directories  in  the  output  mapset,  if  they  do  NOT  exist. 
Map  files  for  dig,  dig_att,  and  dig_  cats  are  also  created  for  the  new  map  layer. 

SEE  ALSO 

msetproj 

AUTHOR 

M.L.  Holko,  USDA,  SCS,  NHOCGIS 
R.  L.  Glenn,  USDA  SCS,  NHOCGIS 
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NAMK 

v.psu  -  Program  to  build  PSU  polygon  and  PSU  sites  from  single  labeled  line  segment. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v.psu 

v.psu  help 

v.psu  input  name  output  =name  psu  name  subj  name  [xdist  =name] 

[ ydist=na/nej 

DESCRIPTION 

Ibis  program  builds  a  complete  PSU  polygon  and  PSU  points  from  a  single  labeled  line  segment 
identifying  me  west  edge  of  the  PSU.  The  resultant  polygon  and  points  will  be  automatically  labeled 
based  on  the  original  line  segment  label. 


Parameters: 
input  =name 
output  name 
psu  name 
subj  name 
\A\A— value 
ydis t=value 


Vector  input  file  name. 
Vector  output  file  name. 
psu_data  file  name. 
Subject  file  name, 
x  distance, 
y  distance. 


EXAMPLE 

psu.vect  in  spri  out  spri.psu  psu  SD009.PNT  subj=bonhon>me.psu 

NOTES 

Refer  to  SCS  PSU  Digitizing  Manual  for  examples  and  further  instruction. 

AUTHOR 

Paul  H.  Fukuhara,  USDA  SCS  National  Cartographic  Center 
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NAME 

v.psujubj  -  Converts  SCS  ISU  PSU  offset  file  to  GRASS  subject  file. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

V.pSD^ubj 
v.psujiubj  help 
v.psu^ubj  input  =name 

DESCRIPTION 

'Ihis  program  converts  a  PSU  offset  file  as  distributed  by  SCS  into  a  GRASS  subject  file  to  be  used 
with  the  SCS  PSU  digitizing  package. 

Parameter: 

inpu t=name  PSU  offset  file  name. 

SEE  ALSO 

Refer  to  the  SCS  PSU  Digitizing  Manual  for  examples  and  further  instruction. 

AUTHOR 

Paul  H.  Fukuhara,  USDA  SCS  National  Cartographic  Center 
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NAME 

v. random  -  Creates  a  GRASS  sitejists  file  of  randomly  placed  symbols  (sites)  within  a  GRASS  vector 
area. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v. random 
v .random  help 

v.random  [-nsv]  map  name  [site=/ia/ne]  dot  =name 
DESCRIPTION 

v.random  allows  a  user  to  create  a  GRASS  sitejists  file  containing  sites  randomly  placed  within  an 
area.  This  program  is  designed  for  demographic  map  areas,  and  may  NOT  perform  well  for  resource 
maps  (very  irregularly  shaped  polygons).  The  user  provides  the  program  with:  a  file  (dot=)  containing 
area  category  names  [default]  (the  -n  option  allows  the  use  of  the  area  category  number)  and  a  count  of 
dots  for  that  name;  input  vector  file  name  (map=),  and  a  sitejists  file  name  (site=).  All  sites  in  the 
sitejists  file  will  have  the  same  category  code  (1).  v.random  is  made  to  work  with  the  mapgen 
mapping  package  to  create  special  symbols  at  the  site  locations. 


Flags: 


-s 


-V 


Use  category  numbers  NOT  names. 
Determine  optimum  dot  size. 
Verbose  mode. 


Parameters: 
map  name 
sit  e  =name 
dot  =name 


Input  vector  file  name. 

Output  sitejists  file  name. 

File  name  containing  labels  and  dot  counts. 


FORMATS 


ITie  dot  file  file  format  is: 

-Using  Names- 
area  name  J  :3 
area  name_2:15 
area  name_3:5 
area  name_n:54 


-Using  Numbers- 
catcgory_num_l  3 
category  _nunul  :15 
catcgory_num_l  3 
category_num_l  34 


SEE  ALSO 

mapgen 

AUTHOR 

R.  I..  Glenn,  USDA  SCS,  NHQ-CG1S 
M.  1..  Ilolko,  USDA  SCS,  NHQ-CGIS 
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NAME 

v. reclass  -  Changes  vector  category  values  for  an  existing  vector  map. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v-reclass 
v  .reclass  help 

v.reclass  [-d]  type  name  input  name  output  namt:  fil e=name 
DESCRIPTION 

v.reclass  allows  a  user  to  create  a  new  vector  map  based  on  the  reclassification  of  an  existing  vector 
map.  The  user  provides  the  program  with  a  category  conversion  file,  input  vector  map  name,  an  output 
vector  map  name,  and  the  type  of  input  map.  There  is  an  option  (d)  to  dissolve  common  boundaries 
between  adjoining  map  areas  of  the  same  re-classed  category  value. 

Note:  The  dissolve  option  will  work  on  only  those  areas  that  are  of  the  same  conversion  category 
value.  If  a  map  area  is  inside  (island)  a  converted  area  and  is  NOT  converted  to  the  same  value,  its 
boundaries  are  output  to  the  resultant  map. 

COMMAND  LINE  OPTIONS 


Flag: 

-d 

Dissolve  common  boundaries  (default  is  no) 

Parameters: 

type=ruwt: 

Select  area,  line,  or  site. 

Options:  area,  line,  site 

input  name 

Vector  input  map  name. 

output  name 

Vector  cxitput  map  name. 

fil  e=name 

Text  file  name  for  category  conversion. 

EXAMPLE 

$GISBASK/etcA.rcclass  -d  input. soils  output  soil  groupu  type  area 

file  convert  I  ,con  vert  2, con  ver  t3 

The  input  map  soils  contains  15  map  area  categories, 
the  conversion  files  contain: 


convert  1 

convert2 

convert3 

1:1 

3:2 

2:3 

10:1 

4:2 

7:3 

12:1 

5:2 

8:3 

15:1 

6:2 

9:3 

11:2 

13:3 

14:3 

Pnxluces  a  new  vector  area  tile  soil_groupa  coni; lining  area’  boundaries  from  soils  with  area  category 
values  of  1,10,12,15  changed  to  category'  1;  values  of  3-6,11  changed  to  2;  and  values  2,7-9,13-14 
changed  to  3.  Any  common  lxxtndaries  ;ire  dissolved. 

NOIT.: 

The  fonnat  for  "category  label”  is: 

if  NO  SI‘A(  l  vS  in  the  labels  if  SI’AC  T5>  in  the  labels 
Alx’  area  name  1 : 

IX-fl  area  name  2: 

12A  .  . 

WWd  area  name  n: 
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v  .reclass 


The  format  for  "category  value"  is: 

1 

10 

12 

15 

INTERACTIVE  MODE 
v  .reel  ass 

o  The  first  question  asked  is  the  map  type: 

Enter  the  type  of  map  (area,  line,  site)  [area]  : 

The  default  is  for  areas. 

o  The  next  question  is  if  common  boundaries  are  dissolved  : 

Do  you  want  common  boundaries  dissolved  ?(y/n)  [n] 

The  default  is  no,  meaning  all  exiting  boundaries  will  be  retained, 
o  The  next  question  is  an  option  for  using  category  labels  : 

Do  you  want  to  use  category  names  ?(y/n)  [n] 

The  default  is  no,  meaning  the  user  will  be  using  category  values. 

o  The  next  question  asks  for  the  name  of  the  input  map  : 

Enter  vector  map 

Enter  ’list’  for  a  list  of  exiting  vector  files 
Ht  RETURN  to  cancel  request 

> 

Any  map  in  the  user’s  search  list  is  available, 
o  The  next  question  asks  for  the  name  of  the  output  map  : 

Enter  name  for  resultant  vector  map 
Enter  ’list’  for  a  list  of  exiting  vector  files 
Ht  RETURN  to  cancel  request 

> 

If  the  name  is  for  an  existing  map,  tire  user  will  be  asked  if  the  map  can  be  over  written, 
o  The  next  question  asks  if  a  file  of  lalxls/categories  is  to  be  used  : 

If  names  was  selected  previously: 

Do  you  want  to  use  a  file  of  labels?(y/h)  [n] 

If  names  was  NOE  selected  previously: 

IX)  you  want  to  use  a  file  of  categories?(y/n)  [n] 
o  At  this  time  the  user  will  lx-  asked  for  category  1  information: 

1.  be  asked  to  enter  a  file  name  if  tile  input  was  selected,  or 

2.  lx-  asked  to  enter  the  information  manually. 

Then  the  user  will  lx  asked  for  ealegon  2  information: 

Then  the  user  w  ill  lx  asked  for  ealegon  3  information: 

Then  the  user  w  ill  lx  asked  for  category  u  information: 

o  When  no  entry  is  provided  the  program  will  begin. 
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SEE  ALSO 

v. extract 

AUTHOR 

R.  L.  Qenn,  USDA  SCS,  NHQ-CC3S 
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NAMK 

v. report  -  Generates  statistics  for  vector  files. 

(S('S  GRASS  Vector  Program) 

SYNOPSIS 

v.report 
v .report  help 

v.report  ( — hfq)  map  name  type  name  [mutn=name[/iame,...]\  [pi  =value]  [pw  =value] 
DESCRIPTION 

v.report  generates  a  table  showing  the  area  present  in  each  of  the  categories  of  a  user-selected  data 
layer.  Area  is  given  in  hectares,  square  meters,  and  square  kilometers.  If  the  units  option  is  used,  area 
is  given  in  acres,  square  feet,  and  square  miles,  v.report  works  on  the  map  data;  therefore,  the  current 
region  and  mask  are  ignored. 


Flags: 

h 

-f 


Suppress  page  headers. 

Use  formfeeds  between  pages. 
Run  quietly. 


Parameters: 

map  name  vector  map  to  report  on. 

type  =name  Type  of  vector  map. 

Options:  area,  line,  site 

units  =name,name, .. . 

mi(les),  f(eet),  me(ters),  kilometers),  a(cres),  h(ectacres),  c(ounts). 

pi  —value  Page  length,  in  text  lines. 

Default:  0 

pw  value  Page  width,  in  characters. 

Default:  79 


EXAMPLE 

Following  is  a  sample  table  generated  by  v.report  where  type=area. 

v .report  -hfq  map=soils  type  area  units  c,me 


+ - - - 

. . + 

vtCTCR  MNP  CAIKLKi  REPLKT  ! 

|IJXATICN:  spearfish 

i  .  _  _ 

\ted  Apr  24  15:59:22  1991  [ 

_  _ | 

1 

|  north:  4928000 

east : 

609000 

1 

1 

IWTNDCW  south:  4914000 

west : 

590000 

1 

j  res:  100 

i  _  _ 

res : 

100 

1 

_  _  I 

i  . i 

[MNP:  soi is  in  grass  | 

i  l 

i 

j  Category  Information 

1 

|  |  square  | 

|  #|descript ion 

i  .  _  _ 

jeount  j  meters  j 

. . j 

1 

|  0  |no  data . 

.  .  .  |  0  |0 .00000000e+00 1 

|  1  |AaB . 

. 

.... 

.  .  .  j  1  jl  .7U69450e-K)5  | 

1  2|Ba . 

. 

.  ... 

.  .  .  |  2 |5.85232360e+05  | 

1  3|Hb . 

.  .  .  . 

.  .  .  j  5 |6.6537 1740c+05 j 
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|  4  |BcB . |  7  |9 . 18686470e+05 

j  5  |BcC . |  13  j  1 . 23052087 e+06 

I  6|BeE . j  15  |7.16046145e+06 

j  7  |BhE . j  23  |2.30631653e+06 

j  8  |BkD . |  9  |1.26339976e-K)6 

I  9  jdE . j  18  |3 .53705437e+07 

jlojCaD . j  15|2.95884910e+06 

jll|CaE . j  18  (3 .50254750e+06 

|12|Cc . j  2  jl  .  11726840e+05 

j  13  jCJBE . |  8  |4 ,34185839e+07 

|14  |GaD . j  3  jl .  12212602e+06 

j  15  |GcD . j  2  |2 . 17705920e+05 

1 16  |GdE . j  2  jl  .  81687130e+05 

|54|Kb . |  5  |3 .81216040e+06 

|55  j . j  1  j  1.083 10000e-K)2 


I1QC4L  |  735  1 2 . 82 1 8254  7e+08  j 

+ . - . . . . . - . - . + 


Following  is  a  sample  table  generated  by  v. report  type=line. 

v .report  -hfq  m uploads  type=4ine  units=3:,me/ 


|  MOCK  ,VWJ  CAnHPY  REPCKT 

. -  + 

1 

|LOCATICN:  spearfish 

j . 

Wfcd  Apr  24 

16:34:24  1991 | 

|  north:  4928000 

east : 

609000 

-  -  --  | 

1 

|WINDCW  south:  4914000 

west : 

590000 

1 

j  res :  100 

1 _ 

res : 

100 

1 

1 

i  - i 

|MAP:  roads  in  grass  | 

l  _  .  _ _  _  i 

j  Category  Information 

1  1 

1 

- l 

1 

|#|descript ion 

1 _ 

|count  | 

meters  | 

feet  | 

1 

|0  |no  data . 

1  5| 

0 .0000000e+00  | 

0 .0000000e+00  | 

|l  [interstate . 

1  51  | 

7 ,5353920e+04 j 

2 .4722114e+05 | 

|2  Iprirmry  highvay,  hard  surface. 

1  60 1 

4.4100270e+04  j 

1 .446841 7e+05 | 

|3 (secondary  highvay,  hard 

surface 

1  42 1 

3  .4949180e+04  | 

1.1466127e+05 j 

|4  |1 ight-duty  road,  inprvd 

surface 

1  512| 

1 ,8597865e+05  j 

6.1015875e+05  j 

|5  |uninproved  road.  .  .  . 

j _ 

•  •  • 

1  153 1 

2 .2649644e+05 j 

7 ,4308952e+05  | 

I'lOCAL 

t — - - 

|  823  ( 

5 .6687846e+05  ( 

1.8598149e+06| 

- - + 
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Following  is  a  sample  table  generated  by  v.report  where  type=sites. 

v .report  -hfq  map  =bug  sites  type=ates  unitse 

NOTE:  count  is  the  ONLY  option  available  for  site  maps. 


+ . . . . . - - - - + 

|  VtCICRM^P  CAEEUY  REFCFT  | 

jlGCAnCN:  spearfish  \ted  Apr  24  16:41:17  1991  [ 


|  north:  4928000  east:  609000 
|WINXW  south:  4914000  west:  590000 
i  res:  100  res:  100 


(foftP:  bugsites  in  grass 


Category  Information  | 

#|descr ipt ion  |count 


Ml . I  1| 

I  21 . |  1| 

I  3| . |  1| 

I  4| . |  1| 

I  5| . |  1| 

I  6| . |  1| 

I  7| . •  .  .  .|  1| 

|90| . ’ . |  l'| 


|TOLAL  |  90 1 

+ . . . + 


After  the  table,  the  user  is  given  the  options  of  printing  out  a  copy  erf  the  report  and  of  saving  the 
report  in  a  file. 

AUTHOR 

R.  L.  Glenn,  USDA  SCS,  NHQ-CX3S 
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NAME 

v.rmedge  -  Selects  edge  vectors  from  an  existing  vector  map,  removes  them,  and  creates  a  new  vector 
map. 

(SCS  GRASS  Vector  Program) 

SYNOPSIS 

vjrmedge 
v-rmedge  help 

vjrmedge  input  =name  output  =name 
DESCRIPTION 

v.rmedge  allows  a  user  to  create  a  new  vector  map  from  an  existing  vector  map,  however  ALL 
OUTER  boundaries  will  be  gone.  Any  outer  edge  that  needs  to  be  retained  will  require  adding  another 
outside  boundary;  v. digit  can  be  used  to  provide  this  additional  boundary. 

Parameters: 

input  =name  Name  of  vector  input  hie. 

output  =ru2/ne  Name  of  vector  output  tile. 

NOTES 

When  using  v. digit  to  add  an  additional  boundary  to  a  map,  it  may  be  necessary  to  break  the  boundary 
of  an  existing  area.  The  user  *  *  *  MUST  REMEMBER  *  *  *  that  breaking  the  boundary  of  a  named 
area  ***  REMOVES  THE  IABEL  ***,  and  the  area  *•*  MUST  BE  RELABELED  ***  prior  to 
leaving  vxligit; 

OR 

* «*  vjrmedge  will  REMOVE  that  area  boundary  ALSO  *** 

This  will  result  in  MISSING  data  in  a  patching  operation. 

SEE  ALSO 

vuiigit,  v merge,  v. patch 
AUTHOR 

R  L.  Glenn,  USDA  SCS,  NHQCXHS 
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NAME 

vjc ale. random  -  Creates  a  sitejists  file  of  randomly  placed  symbols  within  a  GRASS  vector  area. 
(SCS  GRASS  Vector  Program) 

SYNOPSIS 

v. scale  j~andom 
v.scalej-andom  help 

v.scale-random  [  — n]  map  name  site  namt!  do t=name  [ outdot  =name \ 
scale  =value  [ cover  =value]  [six e -value] 

DESCRIPTION 

vacate. random  allows  a  user  to  create  a  GRASS  sitejists  file  containing  sites  randomly  placed  within 
an  area.  This  program  is  designed  as  an  interface  to  v.random  to  aid  the  user  in  determining  the 
number  of  dots  to  locate.  This  progam  uses  the  same  type  of  file  listing  the  category  and  counts.  This 
file  is  then  modified  to  try  to  produce  a  pleasing  dot  count  for  a  map  of  a  specified  scale. 

COMMAND  LINE  OPTIONS 


Flag: 

-n 

Use  category  values,  NOT  category  names. 

Parameters: 

map  =name 

Input  vector  file  name. 

sit  e=name 

Output  sitejists  file  name. 

dot  name 

Name  of  file  containing  labels  and  counts. 

outdot  name 

Name  of  new  file  to  contain  scaled  counts. 

scale  =value 

The  denominator  of  the  map  scale. 

Options:  1  -  999999999999 

cover  =value 

The  fraction  of  the  most  dense  area  to  cover  with  dots. 
Options:  0  -  1 

size=value 

The  size  of  each  dot,  in  centimeters. 

Options:  0  -  100 

SEE  ALSO 

s.menu,  v.random 

AUTHOR 

M.  L.  Ifolko,  USDA  SCS,  NHOCGIS 
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FORMAT  DESCRIPTIONS 


This  chapter  contains  descriptions  of  file  formats  and  drivers  used  by  some  GRASS  programs. 

Other  software  also  distributed  with  GRASS  is  not  documented  in  this  volume;  this  includes  programs 
contained  under  the  src. garden  and  src.rclatcd  directories  that  the  user  must  compile  separately  (see  the 
GRASS  Installation  Guide  for  compilation  instructions).  The  sre.garden  directory  includes  program 
interfaces  that  link  GRASS  4.0  with  other  related  software  (including  UW-RIM  and  BNOISE).  The 
src. related  directory  includes  programs  to  which  GRASS  has  been  interfaced  that  program  developers  have 
allowed  to  be  distributed  with  GRASS  (such  as  UW-RIM  and  BNOISE,  MAPGEN,  GCTP,  PBMPLUS, 
and  XGEN).  These  programs  are  described  in  their  original  program  documentation. 
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NAME 

imagery  -  Description  of  GRASS  image  processing  functions. 

IMAGE  PROCESSING  IN  GRASS 

The  followii^  discussion  is  intended  to  provide  a  quick  overview  of  image  processing  in  GRASS. 
Some  concepts  and  some  hints  are  provided.  For  a  more  complete  discussion  and  description  of  image 
processing  in  GRASS  see  GRASS  Tutorial:  Image  Processing. 

EXTRACTING  IMAGERY  DATA  INTO  A  GRASS  DATABASE 

Remotely  sensed  images  are  captured  for  computer  processing  by  filtering  radiation  emanating  from  the 
image  into  various  electromagnetic  wavelength  bands,  converting  the  overall  intensity  for  each  band  to 
digital  format,  and  storing  the  values  on  computer  compatible  media  such  as  magnetic  tape. 

I  he  GRASS  programs  that  extract  image  data  from  magnetic  tape  can  read  LANDSAT  multi-spectral 
scanner  (MSS)  data  (i. tape. mss),  IANDSAT  thematic  mapper  (TM)  data,  ( i.tapeJm ),  and  other 
formats,  such  as  scanned  aerial  photography  or  SPOT  satellite  data  (i.tape. other).  They  extract  the 
band  data  into  raster  files  in  a  GRASS  data  base.  Each  band  becomes  a  separate  raster  file,  with 
standard  GRASS  map  layer  support,  and  can  be  displayed  and  analyzed  just  like  any  other  raster  file. 

UNREGISTERED  DATA 

I  he  band  data  extracted  from  tapes  are  assumed  to  be  unregistered  data.  This  means  that  the  GRASS 
software  does  not  know  the  earth  coordinates  for  pixels  in  the  image.  The  only  coordinates  known  at 
the  time  of  extraction  are  the  columns  and  the  rows  relative  to  the  way  the  data  were  stored  on  the 
tape. 

Dita  can  only  be  extracted  into  a  data  base  that  has  an  x,y  coordinate  system,  and  not  into  a  projected 
data  base  (e  g.,  a  UIM  data  base).  This  is  to  prevent  users  from  mixing  the  unregistered  data  with 
registered  data  in  the  same  data  base.  The  GRASS  system  comes  with  the  data  base  imagery,  which  is 
an  x,y  data  base.  New'  data  bases  can  be  created  by  users  during  GRASS  startup.  See  the  g.help 
section  on  "Setting  Up  a  GRASS  Database"  for  instructions  on  creating  a  new  data  base. 

CELL  HEADERS 

Ihe  cell  headers  for  tltc  band  files  in  these  x,y  data  bases  are  set  to  reflect  the  rows  and  columns  of  th 
extracted  data.  Ihe  north-south  values  represent  the  rows,  and  the  east-west  values  represent  the 
columns.  Ihe  resolution  of  the  unregistered  data  is  set  to  1. 

Note,  however,  that  while  the  row  numbers  increase  from  1  to  n  from  north  to  south,  GRASS  requires 
that  the  values  of  the  user’s  current  geographic  region  decrease  from  north  to  south.  Ihe  solution 
adopted  was  to  represent  the  rows  w'ith  negative  values  (i.e.,  -1  to  -n).  litis  allows  them  to  decrease 
from  north  to  south  and.  if  the  minus  sign  is  ignored,  to  reflect  the  row  numbers. 

Ihe  cell  headers  for  the  layers  in  x,y  data  bases  are  set  so  that  the  coordinates  at  the  center  of  each 
pixel  exactly  reflect  the  row  and  column  for  that  pixel.  The  northern  edge  is  set  to  05  less  than  the 
first  row,  the  southern  edge  05  larger  than  the  last  row ,  the  west  to  05  less  than  the  first  column,  and 
the  cast  to  05  larger  than  the  last  column.  When  the  image  is  displayed  on  the  graphics  monitor,  the 
(I. where  command  can  lx.’  used  to  re|xxl  row  and  column  values. 
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For  example,  suppose  rows  100-500  and  columns  200-800  are  extracted.  Then  the  cell  headers  for  the 
extracted  data  will  be  given  the  following  values: 


north: 

-99.5 

south: 

-500.5 

west: 

199.5 

east: 

800_5 

ns  res: 

1.0 

ew  res: 

1.0 

REGION  AND  MASK 

Since  the  data  layers  are  given  essentially  contrived  cell  headers,  users  must  exercise  extra  care  when 
analyzing  or  displaying  unregistered  images.  It  is  very  easy  for  the  user’s  GRASS  region  to  have 
absolutely  no  relationship  to  the  data  the  user  is  attempting  to  display.  This  could  happen  when  the 
region  is  set  for  data  extracted  from  one  tape,  but  the  analysis  is  attempted  on  data  extracted  from 
another  tape.  A  good  habit  to  develop  is  to  set  the  region  to  exactly  match  one  of  the  band  files.  This 
can  be  done  using  the  GRASS  g. region  command. 

Another  pitfall  is  to  have  a  mask  set  to  a  hand  file  from  one  data  set  while  trying  to  read  another. 
Even  if  the  region  is  set  properly,  the  data  will  appear  to  be  all  no-data  since  the  mask  will  effectively 
knock  out  any  data.  Be  sure  that  the  mask  is  either  set  to  a  related  data  layer  or  not  set  at  all.  See 
r.mask  for  information  on  setting  and  unsetting  the  mask. 

Please  note  that  the  tape  extraction  routines  set  your  data  base  region  to  match  the  rows  and  columns  of 
the  data  that  is  extracted. 

GROUPS 

Since  the  band  files  are  individual  raster  files,  it  is  necessary  to  have  a  mechanism  to  maintain  a 
relationship  between  band  files  from  the  same  image  as  well  as  raster  files  derived  from  the  band  files. 
The  GRASS  group  data  structure  accomplishes  this  goal.  The  group  is  essentially  a  list  of  names  of 
raster  files  that  belong  in  the  group.  For  user  convenience,  groups  are  also  created  (and  updated)  by  the 
tape  extraction  routines.  The  tape  extraction  programs  ask  the  user  to  supply  a  group  name  as  well  as 
to  specify  the  bands  to  be  extracted.  Suppose  that  the  user  extracts  bands  1,  2,  and  3  into  a  group 
called  nhap.  Then  the  band  files  will  become  the  raster  files  nhap.l,  nhap.2,  and  nhap.3  and  the 
group  nhap  will  list  these  3  raster  files  as  members  of  the  group. 

Groups  can  also  be  created  and  modified  by  the  user  using  the  GRASS  command  i.group. 

IMAGE  REGISTRATION  AND  RECTIFICATION 

Image  registration  and  image  rectification  is  the  process  of  associating  earth  coordinates  with  pixels  on 
the  image  and  then  converting  the  unregistered  raster  files  to  raster  files  in  a  projected  data  base. 

Image  registration  ( i.points )  is  applied  to  a  group,  rather  than  to  individual  raster  files.  The  control 
points  are  stored  in  the  group,  allowing  all  related  band  files  to  lx:  registered  in  one  step  rather  than 
individually. 

Image  rectification  ( i.rectify )  is  applied  to  individual  raster  tiles,  with  the  control  points  for  the  group 
used  to  control  the  rectification  and  the  group  target  {i. target)  used  to  specify  tlie  data  I  rase  w  here  the 
rectified  layer  will  live. 

IMAGE  CLASSIFICATION 

Image  classification  methods  process  all  or  a  subset  of  the  band  files  as  a  unit.  Spectral  signatures  for 
the  image  are  generated  ( i.cluster )  and  then  used  to  prtxluce  a  landcover  map  ( i.maxlik ) 
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l he  signatures  must  be  associated  only  with  the  raster  files  actually  used  in  the  analysis.  rIhis  means 
that  with  a  group  subgroups  must  be  created  ( i. group )  that  list  the  band  files  to  be  grouped  for 
classification  purposes.  The  signatures  are  stored  with  the  subgroup. 

Note  that  multiple  subroups  can  be  created  within  a  group.  This  allows  different  classifications  to  be 
run  with  different  combinations  of  band  files. 

Also  note  that  raster  files  produced  by  the  classification  process  ( i.maxlik )  are  automatically  listed  as 
part  of  the  group. 

RECTIFIED  VS.  UNRECTIFIED  ANALYSIS 

There  are  two  possible  routes  for  processing  image  data.  The  first  is  to  register  the  group  ( [.points ), 
perform  the  analyses  on  the  unrectified  band  data  ( i.maxlik ),  and  then  rectify  the  results  ( i.rectify ). 
The  second  is  to  register  the  group  ( i.points ),  rectify  the  band  data  ( i.rectify ),  then  run  analyse,  on  tlie 
rectified  band  data  in  the  taiget  location  ( i.rectify ).  Both  routes  are  permissible  in  GRASS.  Users  will 
most  likely  prefer  the  first.  The  second  route  requires  leaving  GRASS  and  re-running  GRASS  under 
the  taiget  location.  It  also  will  require  that  a  group  be  created  to  hold  the  rectified  band  hies  since 
i.rectify  does  not  create  or  modify  groups.  A  so,  spatial  filtering  may  not  be  as  effective  on  rectified 
data  since  the  rectification  of  the  data  requires  resampling  the  original  data. 

SEE  ALSO 

GRASS  Tutorial:  Image  Processing 

d.where,  g.region,  i  cluster,  i.group,  i.maxlik,  i.po'its,  i.rectify,  i.tape.other,  i.tape.mss, 
i.tape.tm,  i. target,  r.mask 

AUTHOR 

Michael  Shapiro,  U.S.  Army  Construction  rngiiv  “ring  Research  Laboratory 
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NAME 

monitorcap  -  Inscription  of  device-driver  data  base  file  format. 

DESCRIPTION 

The  djnon  command  and  all  graphics  commands  access  a  device-driver  data  base  stored  in  the  file 
$GISB ASE/etc/moni torcap.  This  file  contains  a  line  for  each  graphics  monitor  on  the  system.  Each 
line  contains  six  fields  separated  by  colons: 


name 
program 
description 
(if os 

tty 

msg 


The  name  by  which  the  user  identifies  the  driver 

The  full  pathname  of  the  executable  driver  or  a  pathname  relative  to  SGI SB  ASF. 

A  short  four-  or  five-word  description  of  die  driver. 

Rill  pathnames  to  the  input  and  output  fifos  over  which  the  driver  communicates 
with  the  libraries 

The  name  of  the  tty  from  which  the  driver  must  be  started,  or  empty  if  there  is  no 
such  restriction 

A  message  to  print  to  the  user  if  an  attempt  is  made  to  start  the  driver  from  the 
wrong  tty. 


EXAMPLE 

The  following  is  an  example  of  a  single-monitor  system.  The  driver  may  be  started  from  any  terminal 
and  uses  /dev/fifoa  and  /dev/fifoh  for  communication  with  application  programs: 


x:driver/X:graphics  monitor:/dev/fifo.a  /dev/fifo.b::any  terminal 


This  example  has  2  monitors  on  the  system,  using  the  same  device  driver.  Note  that  each  has  a 
different  name  field  and  uses  a  (Efferent  pair  of  fifos.  Also,  each  must  be  started  on  a  specific  terminal: 

l:driver/X:monitor  l:/dev/fifo.la  /dev/fifo.lb:/devAty8:tty8 
2:driver/X:monitor  2:/dev/fifo.2a  /de\7fifo2b:/dev/ttyl0:ttyl0 

NOTES 

Each  line  in  this  file  must  refer  to  a  valid  driver.  No  comment  lines  are  supported.  Also,  no  blank 
lines  are  allowed. 

SEE  ALSO 

d.mon 
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NAME 

paint  -  Description  of  hardcopy  color  output  system  for  GRASS. 

INTRODUCTION 

The  paint  system  allows  the  user  to  produce  color  hardcopy  maps  of  vector,  raster,  and  sites  file  data 
at  any  scale.  For  a  discussion  of  the  GRASS  paint  functions,  see  the  manual  entries  for  p.chart, 
p.colors,  p.icons,  p.labels,  pjnap,  p. screen,  and  pjelect. 

FAINT  DEVICES 

The  GRASS  paint  system  supports  multiple  color  printers  using  a  device  driver  concept.  The  paint  (p.) 
functions  listed  above  send  graphics  requests  to  device- dependent  paint  drivers.  These  drivers  translate 
the  application  requests  into  device-dependent  requests  to  produce  hardcopy  maps. 

INSTALLING  A  PAINT  DRIVER 

A  number  of  paint  drivers  have  been  distributed  with  GRASS.  The  installation  of  a  driver  is  a  two-step 
process.  The  first  involves  identifying  the  drivers)  which  correspond  to  printers)  connected  to  your 
system  and  compiling  those  drivers.  The  second  involves  telling  each  driver  which  i b  port  it  is  to  use. 


1  Ihe  source  code  for  the  drivers  lives  in  $GISBASF/../src/paint/Drivers  Clhe  variable  GISBASE 
refers  to  the  directory  in  which  GRASS  is  installed  on  your  system.) 


Ihe  selection  and  compilation  of  the  drivers  is  done  when  GRASS  is  compiled  as  a  whole. 

2  The  port  configuration  is  handled  using  the  UNIX  In  command. 

Each  driver  expects  to  send  its  output  to  /des /driver.  For  example,  the  tek4695  driver  expects  to 
find  a  tektronix  4695  (or  4696)  printer  on  /devAek4695. 


Suppose  the  printer  is  actually  on  /devAtylO.  Then,  a  link  named  /devAek4695  is  made  to 
/dev/tty  1 0: 


In  /devAtylO  /devAek4695 


NOTES 

’  I  here  are  2  drivers  which  do  not  use  i  b  ports.  One  is  llie  preview  driver,  which  sends  its  output  to  the 
graphics  screen  instead  of  a  hardcopy  printer.  This  tlriver  is  very  handy  and  should  definitely  be 
compiled  on  your  system. 


Ihe  other  is  the  null  driver,  which  is  used  for  debugging  purposes  and  probably  should  not  be 
compiled  on  your  system. 


If  you  compile  either  of  these  drivers,  you  shouldn’t  create  a  /dev  file  for  them. 
SEE  ALSO 

p.chart,  p.colors,  p.icons,  p.labels,  p.map,  p.screen,  and  p.selecl 

AUTHOR 

Michael  Shapiro,  U  S.  Anny  (a instruction  Engineering  Research  Laboratory 
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NAME 

sites.S  -  Description  of  the  GRASS  sjnenu  "S'  interface  option. 

DESCRIPTION 

This  describes  the  GRASS  sjnenu  "S'  statistical  package  interface  option.  See  also  the  manual  entry 
for  sjnenu. 

SPECIAL  ADJUSTMENT 

Due  to  the  fact  that  "S'  references  all  subscripts  beginning  with  1,  and  the  GIS  data  begins  with  0,  it 
was  necessary  to  add  1  to  the  category  numbers.  Therefore,  category  value  0  ("no  data")  becomes 
category  value  1,  category  1  becomes  category  2,  etc. 

S  DATA  STRUCTURES 

Below  are  descriptions  of  the  data  structures  created  by  the  interface.  As  a  general  comment,  within 
"S",  simply  typing  the  data  structure  name  will  display  the  values  contained  in  the  structure.  You  may 
also  find  it  interesting  to  display  the  data  structures  using  the  "S"  function  dput(). 

cat.histo,  (cat.&hlzto) 

This  structure  contains  the  histogram  for  the  categories  in  each  map  layer.  The  histogram  contains  the 
number  of  cells  of  each  category  that  occur  in  the  user’s  geographic  region  (see  wind.n,  et  al.,  below). 
B  is  a  2-dimensional  integer  array  (matrix).  The  first  subscript  references  the  map  layer.  The  second 
subscript  references  the  category  value. 

examples: 

catJiisto[2,5]  is  the  cell  count  for  layer  2,  category  5. 
cathisto(2,]  is  the  full  histogram  for  layer  2. 

Note:  since  more  than  one  layer  may  occur  in  the  data,  and  the  number  of  categories  in  each  layer 
varies,  it  was  necessary  to  create  this  structure  with  sufficient  dimension  to  hold  the  largest  category 
value  for  all  layers.  Histogram  data  for  categories  which  do  not  occur  are  set  to  NA  f’S"  notation  for 
"no  data").  Haw  ever,  there  is  also  an  individual  histogram  structure  for  each  layer:  cat.l.histo, 
cat2iiisto,  etc.  These  are  simple  vectors. 


This  structure  contains  the  names  for  the  categories  in  each  map  layer.  It  is  a  2-dimensional  character 
array  (matrix).  The  first  subscript  references  the  map  layer.  The  second  subscript  references  the 
category. 


Examples: 

cat  .name}  2  r>]  is  the  name  of  category  5  for  layer  2. 
cat.name[2,]  are  all  category  names  for  layer  2. 

Note:  since  more  than  one  layer  may  occur  in  the  data,  and  the  number  of  categories  in  each  layer 
varies,  it  was  necessary  to  create  this  structure  with  sufficient  dimension  to  hold  the  hugest  category 
value  for  all  layers.  Names  for  categories  which  do  not  occur  are  set  to  ”.  However,  there  is  also  an 
individual  category  name  structure  for  each  layer:  cat.l.namc,  cat.2.name,  etc.  These  are  simple 
vectors. 

site.dat* 

This  stmeture  contains  the  data  for  each  site.  It  is  a  3-dimensional  integer  array,  The  first  sul script 
references  the  categories  which  occurred  at  the  site.  The  second  subscript  references  the  site.  The  third 
subscript  references  the  layer. 
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Examples: 

site.data(p3]  is  the  data  for  site  5  in  layer  3. 
site.data{3»]  is  the  data  for  site  2  in  all  layers. 
site.data[,4]  is  all  site  data  for  layer  1. 

Note:  the  size  of  the  first  dimension  will  be  the  number  of  cells  in  a  site,  the  size  of  the  second 
dimension  will  be  the  number  of  sites,  the  size  of  the  third  dimension  will  be  the  number  of  layers. 

sitejmodc 

Since  "S"  does  not  provide  a  statistical  mode  function,  this  structure  contains  the  most  frequently 
occurring  category  few  each  site  in  each  layer.  It  is  a  2-dimensional  integer  array  (matrix).  The  first 
subscript  references  the  site.  The  second  subscript  references  the  layer. 

Examples: 

sitejnode(53]  is  the  mode  for  site  5  in  layer  3. 
sitejnode(2,]  are  the  modes  for  site  2  in  all  layers, 
site .mode[  ,1]  are  all  site  modes  few  layer  1. 

Note:  this  ’mode’  is  not  the  strict  definition  of  the  mode.  Since  category  0  (which  in  "S”  is  category 
1)  represents  "no  data"  in  the  GIS  data  bases,  it  was  excluded  from  the  mode  calculations  (essentially  as 
if  it  had  been  NA).  For  example,  if  the  data  for  a  site  are  11112232311, the  mode  will  be  2. 

layer  .name 

This  structure  contains  the  raster  map  layer  names.  It  is  a  2-dimensional  array  (i.e.,  a  matrix).  The  first 
subscript  references  the  map  layer,  llie  second  subscript  selects  either  the  map  layer  name,  or  the  map 
layer  title. 


Examples: 

layer .n;une[3,l]  is  the  name  of  layer  3- 
layer ,name[3]  is  also  the  name  of  layer  3. 
Iayer.n;une[2]  is  the  name  of  layer  2. 
Iayer.name{33|  is  the  title  for  layer  3. 


location 

Ihis  is  a  simple  character  vector  giving  the  GRASS  location  from  which  the  data  was  extrack'll. 


mapset 

Ihis  is  a  simple  character  vector  giving  the  GRASS  mapset. 

nlayers 

Ihis  is  a  simple  integer  givii*;  the  niimlier  of  map  layers. 


nsites 


sitc.C 


sitc.n 


Ihis  is  a  simple  integer  giving  the  number  of  sites. 

Ihis  is  a  simple  integer  vector  giving  die  geographic  casting  for  each  site. 
Ihis  is  a  simple  integer  vector  giving  die  geographic  northing  for  each  site. 
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This  is  a  simple  character  vector  giving  the  description  for  each  site. 

rftdUt 

This  is  a  simple  character  vector  giving  the  name  and  description  of  the  site  lists  file  from  which  the 
sites  were  taken. 

windji,  wind wind.w,  wind.* 

These  are  simple  real  numbers  giving  the  north,  south,  west,  east  of  the  mapset’s  current  geographic 
region. 

wind  .res 

This  is  a  simple  real  number  giving  the  GRASS  data  base  resolution  (in  meters). 


S  MACROS 

You  may  find  the  following  "S"  macros  helpful  when  referencing  the  ’site.data’  and  ’site.mode’ 
structures,  since  they  allow  you  to  specify  parameters: 

MACRO  site.data(site,  layer) 

({ 

site.dataf  ,  site,  layer] 

» 

END 

MACRO  sitemode(site,  layer) 

({ 

site.mode[site,  layer] 

}) 

END 

MACRO  USAGE 

To  select  the  site.data  for  all  sites  for  layer  2: 

?site.data(layer=2) 

to  select  the  site.data  for  site  4  in  all  layers: 

?site.data(site=4) 

to  select  the  site.mode  for  site  10  in  layer  1: 

?site.mode(layer=l  ,silc=10) 

SORRY,  BUT  ... 

These  macros  are  not  prov  ided  by  ihe  interface.  To  use  these  macros,  you  will  have  to  type  them  into 
a  text  file  and  then,  from  "S”,  issue  the  command: 

definc("<file>) 

SEE  ALSO 

s.db,  s.in.a.scii,  s.menu,  s. out. ascii,  s.surf.idw,  sites. format,  sites.occur,  sites.report 
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NAME 

sites. format  -  Description  of  GRASS  site  list  file  format. 

DESCRIPTION 

This  is  a  description  of  the  site  list  files  found  in  the  GRASS  data  base.  The  files  are  kept  in  the 
site_lists  directory  under  the  current  mapset. 

SAMPLE  SITES  LIST 

Here  is  a  sample  site  list: 

name  (sample 
desc  (sample  site  list 
728220  (5182440(27 
727060  p!81710p8 
725500(5184000(29 
719800(5187200(50 

EXPLANATION 

Each  record  of  data  begins  with  a  named  field  describing  the  record  type,  followed  by  fields  of 
information.  The  fields  are  separated  by  the  pipe  character  |. 

name 

This  field  contains  the  name  of  the  site  list  file,  and  is  printed  on  all  the  reports. 

It  is  permissible  for  this  field  to  be  missing,  since  the  sites  software  will  force  this  field  to  agree  with 
the  name  of  the  site  list  file  itself. 

desc 

This  field  contains  a  description  of  the  site  list  file,  and  is  printed  cm  all  the  reports. 

It  is  permissible  for  this  field  to  be  missing,  in  which  case  the  ate  list  will  have  no  description. 

point 

Each  site  is  described  by  a  ’point’  record.  The  fields  for  this  record  are: 

<tast>  <tiorth>  <ilescription> 

Cast>  casting  for  the  site 

<tiorth>  northing  for  the  site 
<tlescription>  site  description 

The  east  and  north  fields,  which  tire  integers,  must  lie  present  and  valid  or  the  record  itself  will  be 
skipped  by  the  sites  software.  The  description  field  is  optional,  but  recommended. 

BUGS? 

Invalid  records  will  lx  (silently)  ignored  by  the  sites  sofl\\;ire.  Other  record  types  may  be  added  in  the 
future 

SEE  ALSO 

s.db,  s.in.ascii,  s.wenu,  s.oui.ascii,  s.surf.idw,  sites.S,  sites. occur,  siles.report 
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NAME 

sites. occur  -  Description  erf  the  site  occurrence  report  produced  by  s.menu. 
DESCRIPTION 

This  is  a  discussion  erf  the  site  occurrence  report  produced  by  sjnenu. 


SAMPLE  OUTPUT 


SITE  OCCURRENCE  REPCRT 
Yakima  Bring  Center,  Washington 


location:  yakima 
Mapset:  sample 

Site  List:  arctuerosion  -  arched  ogy  (34  sites) 

Analysis  Region: 

north:  5199975.00 

west:  692975.00  east:  737975.00 

south:  5154975.00 


Layer  arch_  survey  Arched ogic  Survey  Areas  (archusurvey) 

cells  in  analysis  region:  810000 
sites  in  analysis  region:  34 


Site  Characteristics 

cells 

cover 

% 

cover 

expected 

sites 

actual 

sites 

chi 

square 

degrees 

of 

freedom 

(  0)  No  data 

764310 

11 

(  1)  Hartmann, phase  1 

25821 

565 

192 

6 

9.088 

1 

(  2)  Hartmann, phase  2 

11032 

24.1 

82 

14 

4.084 

1 

(  3)  Wapora, phase  3 

8837 

193 

66 

3 

1.945 

1 

Totals 

45690 

100.0 

34.0 

23 

15.117 

2 
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EXPLANATION 

The  "Site  Occurrence  Report”  provides  aggregate  site  information  organized  by  raster  map  layers. 

The  report  header  contains  the  following  information: 

Location 

GRASS  data  base  location  (eg.,  yakima), 

Mapatt 

GRASS  mapset  (eg.,  sample) 

Analysis  Region 

The  rectangular  area  in  which  the  analysis  was  run, 
reflecting  the  current  geographic  settings  of  the  user’s 
mapset. 

Site  List 

Name  and  description  of  the  site  list  used  for  the  report  and 
the  number  of  sites  in  the  list.  See  manual  entry  for  sjmemi 
for  more  discussion  about  these  site  lists. 

The  rest  of  the  report  is  divided  into  reports  for  each  raster  map  layer  specified  by  the  user.  In  this 
SAMPLE  OUTPUT,  only  one  map  layer  (arch, survey)  was  specified. 

Certain  information  heads  up  each  erf  these  reports: 

layer 

Identifies  the  raster  map  layer  along  with  the  map  layer  tide. 

cells  in  analysis  region 

The  size  of  the  analysis  region  (in  cells). 

sites  in  analysis  region 

The  number  of  rites  in  the  analysis  region. 
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For  each  map  layer  category  that  occurs  in  a  cell  falling  within  the  boundaries  of  the  analysis  region,  as 
well  as  totals  for  the  map  layer  as  a  whole,  various  statistics  are  presented: 


Site  Characteristics 

These  are  the  numbers  (i.e.,  values)  and  names  (ie., 
descriptions)  for  each  category  (i.e.,  characteristic)  tb*t 
occurs  in  the  map  layer. 


cells  cover 

The  number  of  cells  in  the  analysis  region  having  the 
categoiy  value  (i.e.,  site  characteristic). 


%  cover 

The  predominance  of  the  category  within  the  analysis 
region. 

expected  sites 

The  number  of  sites  in  the  analysis  region  that  would  be 
expected  to  be  observed  having  the  categoiy  value  if  all 
sites  were  evenly  distributed  in  the  region. 

actual  sites 

The  number  of  sites  in  the  analysis  region  that  occurred  in 
cells  having  the  category  value. 


chi  square 

Gives  the  user  a  statistical  test  of  the  hypothesis  that  ate 
distribution  is  dependent  on  environmental  factors.’  For  this 
hypothesis  to  be  true,  the  chi-square  test  must  fail  since  we 
are  calculating  expected  sites  according  to  the  hypothesis 
that  sites  are  randomly  distributed.’ 

degrees  of  freedom 

Number  of  degrees  of  freedom  for  the  chi-square  test.  Fach 
category  value  will  have  1  degree  of  freedom,  and  can  lie 
tested  alone.  The  entire  map  layer  will  have  1  less  degree 
of  freedom  than  the  number  of  categories. 
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NOTE 

Category  zero  (0)  throughout  GRASS  represents  "no  data."  Therefore,  it  is  reported,  but  not  included  in 
the  totals  or  in  the  computation  of  the  chi-square  statistics. 

SEE  ALSO 

s.db,  sin. ascii,  sjnenu,  s. out. ascii,  sjurfjdw,  sites.S,  sites. format,  sites  report 
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NAME 

sites.report  -  Description  of  the  machine  readable  report  output  by  sjnenu. 

DESCRIPTION 

'Ibis  is  a  description  of  the  machine  readable  report  produced  by  the  sjnenu  program. 
SAMPLE  REPORT 

location^akuna|Yakirna  Firing  Center,  Washington 
mapset  (sample 

region  north  (5199975 .000000 
region  south  (5 15497 5  000000 
region  west  (59297 5 .000000 
region  east [737975.000000 
resolution  (50 000000 
site  list(sample|sampie  rite  list 

point  [11728220  (5182440 [27 
point  [2  [727060 (5181710(28 
point  [3  [725500 15184000  [29 
point  |4  [719800 [5187200 p0 

layer[l|arch_suivey|AicheoIogic  Survey  Areas  (arch_survey) 
layer (2  (vegetation [Vegetation  Study  Plots 

cat  [lp  [764310 [No  data 
cat[l  [1  [25821  [Hartmann, phase  1 
cat  (1  p  (11032 |Haitmann,phase  2 
cat[lp(8837|Wapora,phase  3 
cat|2p[774333|no  data 

cat [2 [l  (9299 (stiff  sagebrush/sandbeig  bluegrass  type  (S-l) 

cat [2 [2  [732 pig  sagebmsh/sandberg  bluegrass  type  (S-2) 

cat  [2  [3  [397  puckwheat/sandbeig  Wuegrass  type  (S-3) 

cat  |2|4  [2526  pluebunch  wheatgrass/sandbeig  wheatgrass  type  (S-4) 

cat[2[5  [20184pig  sagebrush/bluebunch  wheatgrass  type  (Lrl) 

cat  [2  p  (82  pig  sagebmshAieedle-and-  thread  type  (1.  2) 


matrix  sizep 

matrix  (-1|-1  p^l  [1  [-1 
matrix  (-lpppflp 
matrix  MtlPtl  Ml 

tiata|l  (lppppppppp 
data(l  [2  (1(1 11(111(1(1  [1(1 
data|l  P  [1  [1 P  (1 P  [1  (1 P  (1 
datafl  (4(1  mn  Mill 
datapllppppppppp 
data(2(2ppppppppp 
data  (2[3|4}4f4pppppp 
data|2  (1  [1  (5  [5 15 15  (5  (5  (5  (5 
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EXPLANATION 

The  machine  readable  report  file  consist  of  lines  erf  text,  with  fields  that  are  separated  by  the  pipe 
character  |.  The  first  field  on  a  line  defines  the  record  type,  and  the  remaining  fields  are  defined 
according  to  the  record  type. 


location 

This  record  gives  the  GRASS  data  base  location, 
location  <Jiame>  <full  name> 


<tiame>  Data  base  location 

<full  name>  Long  name  for  the  location 


■napaet 

This  record  gives  the  GRASS  mapset. 
mapset  <tnapset> 

<mapset>  Mapset  under  which  the  report  was  run 

region 


The  region  records  give  the  mapset  region  coordinates. 


region  north  <N> 
region  south  <S> 
region  west  <W> 
region  east  <£> 

<N> 

North  for  current  region  (float) 

<S> 

South  for  current  region  (float) 

<W> 

West  for  current  region  (float) 

<E> 

East  for  current  region  (float) 

resolution 

lhis  record  gives  the  GRASS  data  base  resolution  in  meters, 
resolution  <Tes> 


<res>  Resolution  of  the  data  base,  in  meters  (float) 

point 

These  records  describe  the  sites  that  were  used  in  the  report.  There  is  one  ’point*  record  for  each  site, 
point  <site_ref><E><N><tlesc> 

<site_rcf>  A  reference  number,  used  by  other  lines  in  the  report  to  reference  this  site 

<£>  Site  easting 
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layer 


cat 


matrix 


matrix 


data 


<N^'  Site  northing 

<lesc>  A  description  of  the  site  (usually  an  site  number) 


These  records  describe  the  map  layers  that  were  used  in  the  report.  'Ihere  is  one  ’layer’  record  for  each 
layer. 

layer  <iayer_ref>  <name>  <fulLname> 


<layer_ref> 
<name> 
<full  name> 


A  reference  number,  used  by  other  lines  in  the  report  to  reference  this  layer 
Name  of  the  map  layer  (raster  file  name) 

Full  name  (title  of  raster  file) 


These  records  give  information  about  each  category  in  each  layer, 
cat  <dayer_ref>  <tat>  <Count>  <name> 


<iayer_ref> 

<tat> 

<count> 

<name> 


Reference  number  of  the  layer 
Category  number 

Number  of  times  this  category  occurred 
Full  name  of  the  category 


size 

This  record  gives  the  number  of  cells  in  each  site, 
matrix  size  <matrix  size> 


<tnatrix  size>  Number  of  cells  per  site. 


These  records  describe  the  locations  of  each  cell  in  the  site  relative  to  the  center  of  the  site, 
matrix  <£w  disp>  <ns_disp> ... 

<Ew._disp>  east-west  displacement  from  the  site 

<ns_disp>  north-south  displacement  from  the  site 

The  displacements  are  in  units  of  1  cell,  which  is  equal  to  the  resolution  of  the  data  base.  They  are 
paired,  and  tlierc  will  be  <matrix  size> pairs.  To  compute  the  coordinates  (or  the  cell: 

north  =  site_north  -  <ns_disp>*  resolution 
cast  =---  site_  east  +  <tw_  disp>*  resolution 


This  is  tli<'  site  data.  'Ihere  is  one  ‘data’  record  for  each  site  tor  each  layer  lhc  -Cat :  held  is  repeated 
<tnatrix  size> times. 
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data  <layer_ref>  <site_ref>  <cat> ... 

<Jayer_ref>  Reference  number  of  the  layer 

<Sate_ref>  Reference  number  of  the  site 

<cat>  Category  which  occurred 

SEE  ALSO 

s.db,  s.in.ascii,  sjttenu,  s.out.ascii,  s.surf.idw,  sites.S,  sites.format,  sitesxxcur 


GRASS  4.0  (Summer  IWI) 
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APPENDIX:  GRASS  VECTOR  DATA  FILE  FORMATS 


David  Genies,  Michael  Higgins,  and  James  Westervelt 
U.S.  Army  Corps  of  Engineers  Construction  Engineering  Research  Laboratory 
P.O.  Box  9005,  Champaign,  IL  61826-9005 


1.  INTRODUCTION 

To  be  used  by  GRASS  programs,  data  must  be  digitally  stored  in  a  GRASS  database.  Data  can  be 
entered  into  a  GRASS  data  base  in  one  of  several  ways: 

(1)  Hardcopy  data  (like  paper  maps)  may  be  either  digitized  or  scanned  into  GRASS’S  vector 
file  format; 

(2)  Data  already  available  in  another  digital  format  (like  ARC-INFO  data)  may  be  converted 
into  one  of  GRASS’S  digital  data  file  formats,  and  stored  in  a  GRASS  database; 

(3)  GRASS  analysis  programs  can  be  used  to  create  new  GRASS  data  from  data  already  stored 
in  a  GRASS  digital  data  fje  format. 

GRASS  commands  operate  on  three  basic  forms  erf  digital  data:  vector  data,  raster  data,  and  sites  data. 
In  whichever  of  these  forms  data  are  represented,  supporting  information  is  needed  to  describe  the  geo¬ 
graphic  location  and  nature  of  the  data  stored. 

For  data  stored  in  GRASS  vector  format,  information  on  the  location  of  vectors,  the  vector  topology, 
vector  category  values,  and  category  labels  are  stared  in  separate  files.  For  data  stored  in  GRASS  ras¬ 
ter  format,  additional  files  are  also  stored  to  hold  information  on  category  colors,  the  map’s  develop¬ 
ment  history,  etc.  Information  on  site  (point)  data  locations  and  categories  are  stored  in  a  single  file. 
The  programs  v  support  and  r support  help  the  user  build  necessary  GRASS  support  files  for  vector  and 
raster  data.1  Many  GRASS  commands  automatically  generate  necessary  support  files.  Refer  to  specific 
GRASS  User's  Reference  Manual  (Westervelt,  Shapiro,  et  al.)  program  manual  entries  to  leam  when  the 
user  must  explicitly  create  support  files. 

This  paper  describes  the  formats  of  files  containing  information  on  data  stored  in  GRASS  vector  for¬ 
mat.  GRASS  vector  format  is  also  referred  to  as  digit  format;  the  GRASS  vector  digitizing  program  is 
named  v. digit. 

USACERL  first  released  this  GRASS  vector  file  format  with  version  3.0,  to  store  vector  data  without  all 
the  topological  infor  iation  and  data  structures  that  are  necessarily  contained  by  files  in  USGS’  Digital 
Line  Graph  (dig)  format.  The  new  digit  file  format  makes  it  easier  to  update  and  edit  files  being  digi¬ 
tized,  while  maintaining  the  accuracy  of  vector  data. 

2.  GRASS  VECTOR  DATA  FILE  FORMATS 

Four  basic  files  are  used  to  represent  the  geographic  location  and  nature  of  data  in  GRASS  vector  file 
format.  These  files  contain  information  on  the  location  of  vectors,  the  vector  topology,  vector 
category  values,  and  category  labels.  GRASS  vector  locations  may  be  stored  in  ASCII  or  binary  for¬ 
mat.  If  the  map  is  digitized  in  GRASS,  another  file  containing  the  coordinates  of  points  used  to  register 
the  map  to  the  digitizing  tablet  is  also  stored. 

Each  file  is  assigned  the  same  name  (a  user-assigned  map  layer  name),  but  is  stored  in  a  separate  sub¬ 
directory  of  the  user’s  current  GRASS  mapset  (i.e.,  different  subdirectories  of  $  LOCATION).  Relevant 
subdirectories  are  shown  in  the  table  below. 


1  Program  prefixes  indicate  whether  command  create  support  files  for  raster  (T")  or  for  vector  ("v")  data. 
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GRASS  VECTOR  DATA  DIRECTORIES: 


dig_asdi: 

dig: 

dig  plus' 
dig_att: 
dig  cats: 
reg: 


Contains  ASCII  files  in  GRASS  vector  (dig)  format. 

Contains  binary  files  in  GRASS  vector  (<£g)  format. 

Contains  topology  information  for  files  in  GRASS  vector 
(dig)  format. 

Contains  die  locations  at  which  category  labels  will  be 
placed  for  files  in  GRASS  vector  (dig)  format. 

Contains  the  category  text  labels  used  for  files 
in  GRASS  vector  (dig)  format. 

Contains  the  geographic  coordinates  of  points  used  to  register 
to  a  known  coordinate  system  a  (vector)  map  layer  digitized  with 
the  GRASS  vxUeit  program. 


3.  HELPFUL  TIPS 

To  import  a  map  layer  into  GRASS  4.0,  at  least  two  files  are  needed.  They  are  a  dig  ascii  file  (or  a 
dig  file,  its  binary  representation)  describing  the  geographic  locations  of  vectors,  and  a  dig  att  file 
describing  map  feature  attributes.  The  dig_aadi  contains  seme  brief  header  information  to  describe  the 
map  region,  etc.,  as  well  as  line  segment  information.  The  attribute  file  contains  information  as  to 
what  type  of  feature  the  attribute  describes,  the  x,y  map  coordinates  of  the  label  placement,  and  an 
integer  number  representing  the  attribute.  It  is  also  recommended  that  a  separate  ASCII  file  be  pro¬ 
vided  with  which  to  cross-reference  these  attributes  with  textual  information. 

There  are  a  few  important  restrictions  on  the  import  files: 

•  Area  attribute  coordinates  MOST  be  located  within  the  area. 

•  Line  attribute  coordinates  MUST  be  closer  to  the  line  they  describe  than  any  other.  This  implies 
that  they  must  NOT  be  located  on  a  node  where  two  or  more  lines  meet. 

•  Vectors  (as  separated  by  A,  L,  and  P  in  the  dig_asdi  file)  must  NOT  cross  one  another.  Instead, 
each  should  be  broken  into  separate  traces  all  ending  at  the  same  point.  This  point  is  then 
defined  as  a  node.  These  lines  should  be  snapped,  (i.e.,  the  common  x  and  y  values  are  exactly 
the  same  value  for  each  vector). 

•  There  should  be  one  and  only  one  vector  defining  a  given  border  or  line  (i.e.,  if  two  areas  share  a 
common  border,  that  border  should  only  be  specified  once).  As  another  example,  if  a  road  (Line 
information)  and  an  area  boundary  (Area  Edge  information)  share  a  common  line  within  the  same 
map  overlay,  this  line  should  be  digitized  once  as  an  Area  Edge  so  that  the  area  may  be  resolved, 
but  the  line  may  also  then  be  given  an  attribute  to  identify  it  as  a  road.  The  user  is  advised  to 
NOT  mix  data  types  like  tins  in  a  single  file,  but  it  may  be  done  in  this  manner. 

•  If  there  are  vectors  that  are  identified  as  Area  Edges,  tins  implies  that  it  is  possible  to  complete 
each  area  by  following  one  or  more  Area  Edges  that  are  connected  by  common  nodes,  and  that 
all  such  line  traces  can  each  be  resolved  into  closed  areas. 
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4.  DIG_ASCD  AND  DIG  FILES  DESCRIBING  GEOGRAPHIC  LOCATIONS  OF  VECTORS 


Like  their  pre-3.0  counterparts,  the  new  dig_ascii  files  have  two  components:  a  header,  and  die  series  of 
vectors  digitized.2  The  header  contains  historical  information,  a  description  of  the  map,  and  its  location 
in  the  universe.  It  consists  of  fourteen  lines.  Each  line  has  two  parts.  The  first  part  of  each  line  is  a 
description  of  the  data  on  that  line,  while  the  second  part  of  the  line  contains  the  data.  A  sample 
dg_ascii  file  header  is  shown  below: 


ORGANIZATION: 

US  Army  Const.  Eng.  Rsch.  Lab 

DIGIT  DATE: 

03A8£l 

DIGIT  NAME: 

rrri chad  higgins 

MAP  NAME: 

v  digit  example 

MAP  DATE: 

12/25/90 

MAP  SCALE: 
OTHER  INFO. 

24000 

ZONE: 

5 

WEST  EDGE: 

608000 j00 

EAST  EDGE: 

630000 DO 

SOUTHEDGE 

3720000 J00 

NORTH  EDGE 

3739000 DO 

MAP  THRESH 
VERTI: 

00.00 

The  description  of  the  data  starts  in  column  1  and  continues  through  column  14.  The  description  is 
left-justified  and  it  MUST  be  padded  with  Hanks  up  to  and  including  column  14.  Data  begins  in 
column  15  of  the  header.  The  size  limits  of  the  header  data  lines  follow  below. 


ORGANIZATION: 

Limited  to  30  characters 

DIGIT  DATE: 

Limited  to  20  characters 

DIGIT  NAME- 

limited  to  20  characters 

MAP  NAME: 

limited  to  40  characters 

MAP  DATE: 

limited  to  11  characters.  Prefer  mm/dd/yy 

MAP  SCALE: 

Integer 

OTHER  INFO: 

Limited  to  73  characters 

ZONE: 

Integer 

WEST  EDGE: 

Real  number  (douHe) 

EAST  EDGE: 

Real  number  (douHe) 

SOUTHEDGE: 

Real  number  (douHe) 

NORTH  EDGE 

Real  number  (douHe) 

MAP  THRESH 

Real  number  (douHe) 

VERTI: 

Unused 

The  first  five  lines  of  die  header  contain  historical  information.  Remaining  lines  contain  information 
about  the  map  and  its  location  that  are  used  by  v. digit.  The  map  edges  (defined  by  the  eastings  and 
northings)  must  describe  a  region  large  enough  to  encompass  the  entire  map.  If  the  MAP  THRESH  is 
unknown  or  irrelevant,  set  it  to  0.0. 

Vectors  appear  in  the  second  portion  of  the  dig_ascii  file,  beneath  the  header  information.  Three  vector 
types  exist:  Area  Edges,  Lines,  and  Points.  The  type  of  vector  appearing  in  the  <Mg_ascii  file  will 
depend  on  the  way  in  which  the  map  features  were  digitized.  In  general,  a  soils  map,  consisting  of  a 
series  of  polygons,  would  have  been  digitized  as  an  Area  Edge;  a  feature  like  roads  or  railroads  would 

2  Note:  The  dig  file  is  a  binary  machine-readable  representation  of  the  dig_ascii  file.  Here,  we  examine  the 
dig_ascii  file  because  it  is  readable  by  the  user. 
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have  been  digitized  as  a  Line  Edge;  a  map  depicting  features  without  area,  like  one  of  sewage  outfalls, 
would  have  been  digitized  as  a  Point. 

Although  possible,  users  are  discouraged  from  placing  both  vector  types  in  the  same  hie.  A  vector  that 
is  used  both  as  an  Area  Edge  and  a  Line  (eg.,  a  road  also  serving  as  a  boundary)  should  be  digitized  as 
an  Area  Edge.  Do  not  double-digitize.  An  example  of  vector  data  as  they  appear  in  a  dig_asdi  file  are 
shown  below.  Vectors  digitized  as  Area  Edges  are  preceded  with  an  A,  while  vectors  digitized  as  Lines 
are  preceded  with  an  L,  and  vectors  digitized  as  points  are  preceded  with  a  P. 


A  3 


372474738 

616579  60 

3724722.69 

613539.73 

3724703.68 
L  3 

61078650 

373486231 

61204333 

3734872.42 

614662.14 

3734871.44 
A  2 

618094.75 

3734871.44 

618094.75 

3734456.04 
A  5 

618142.16 

3734456.04 

618142.16 

3734446 j65 

61820264 

3734407.49 

62052438 

3734107.06 

62052359 

373332651 
L  6 

620526.48 

373281136 

62462086 

3732188.15 

624627 j01 

373171429 

624641.11 

372979089 

62463587 

372963108 

62464055 

372949705 
P  2 

624631.16 

373280025 

624625.46 

3732800 25 

624625.46 

Each  vector  definition  consists  of  two  parts:  a  description  line,  followed  by  a  series  of  coordinate 
pairs.  The  line  describing  the  vector  will  specify  both  the  type  erf  vector  it  is  (Area  Edge,  Line,  or 
Point),  and  the  number  of  points  (coordinate  pairs)  that  were  used  to  construct  the  vector.  For  example, 
in  the  belcw  vector  definition,  the  description  line  contains  the  letter  A  (specifying  that  the  vector  is  an 
Area  Edge),  followed  by  the  number  3  (notifying  us  that  this  vector  consists  of  3  points). 

A  3 

372474738 

61657960 

3724722.69 

613539.73 

3724703.68 

610786.90 

For  each  vector  definition  the  description  line  then  consists  of:  (1)  a  letter  A,  L,  or  P  defining  vector 
type  (as  Area  Edges,  Lines,  or  Points,  respectively),  (2)  followed  by  one  or  more  spaces,  (3)  followed 
by  a  number  stating  the  number  of  points  used  to  define  the  vector.  This  line  can  be  written  using  the 
Fortran  format:  AJ,1X,IS.  Following  the  data  line  that  describes  the  vector  will  be  the  actual  coordi¬ 
nates  of  which  the  vector  consists.  Note  that  the  coordinates  are  stated  as  pairs  of  Northings  and  East¬ 
ings  (y,x),  in  this  order.  This  differs  from  the  format  erf  the  dig  files  used  by  pre-3.0  versions  of 
GRASS,  in  which  this  order  was  reversed.  These  lines  can  be  written  with  the  Fortran  format: 
2(IX,F122). 
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5.  GRASS  VECTOR  ATTRIBUTE  FILE  FORMAT 


GRASS  attribute  files  will  be  used  to  store  attribute  information  associated  with  GRASS  vector  files. 
The  attribute  file  will  contain  category  numbers  that  will  be  used  when  generating  a  raster  (cell)  file, 
and  may  also  be  needed  when  converting  GRASS  files  to  other  systems’  data  formats.  Attribute  files 
will  be  stored  in  ASCII  in  their  own  data  directory  and  can  be  used  by  v digit  or  any  other  GRASS  pro- 
cram.  Ihe  words  attribute  and  category  are  used  interchangeably  in  this  paper. 

There  is  one  type  of  data  line  in  the  attribute  file.  Ihe  data  line  will  specify  the  type  of  map  feature 
(Area,  Line,  or  Point),  category'  location  point  (x,y),  and  a  category  number.  This  category  number 
should  be  cross-referenced  to  a  textual  description  in  a  separate  ASCII  file.  An  example  follows: 

A  62836851  3727988.27  7 


Column 

Data  Field 

i 

lather  an  A  or  L  which  specifies  the  type  of  map  feature. 

(Other  codes  may  and  will  be  allowable  in  the  future.) 

2-3 

Spaces. 

4-15 

Pasting  (x)  of  category  location  point.  Right-justified. 

16-17 

Spaces. 

18-29 

Northing  (y)  of  category  location  point.  Right-justified. 

30-31 

Spaces. 

32-39 

Category'  number.  Right-justified. 

The  category  location  point  for  an  Area  map  feature  must  be  inside  the  area.  A  category  location  point 
for  a  I  ine  feature  must  be  a  point  somewhere  on  the  line,  preferably  towards  the  middle  of  the  line  and 
not  at  a  node.  A  category  located  at  the  nodes  of  lines  would  make  it  difficult  to  determine  the  line 
with  which  the  attribute  is  meant  to  be  associated.  The  category  location  point  for  lines  with  only  two 
points  (which  are  nodes)  will  be  the  midpoint  of  the  line,  which  will  have  to  be  calculated.  The  mid¬ 
point  formula  is  as  follows: 

x  =  (xl  +x2)  / 2,  y  =  (yl  +y2)/2 

Ihe  category  location  point  for  a  Point  map  feature  will  be  the  same  as  that  of  the  Point. 

If  no  attribute  is  associated  with  a  particular  map  feature  then  no  line  will  exist  for  it  in  the  map’s 
dig_att  file. 

Attributes  are  attached  to  their  corresponding  features  by  running  the  GRASS  command  v  support  or 
v. import.  Currently,  if  more  than  one  attribute  is  associated  with  a  feature,  all  but  the  first  will  be 
ignored,  and  a  warning  message  given  to  that  effect.  The  GRASS  User’s  Reference  Manual  (Wester- 
velt,  Shapiro,  et  al.)  details  the  use  of  these  commands. 

A  brief  example  of  an  attribute  file  is  shewn  below: 


L 

386073.72 

3903017.14 

101 

L 

405139.94 

389683827 

102 

L 

403345.13 

3894572.69 

102 

A 

383186.04 

390311752 

524 

L 

386023.05 

3901056.16 

104 

L 

38898059 

3901737.43 

105 

A 

388554.45 

3899862.40 

533 

A 

392332.92 

390034536 

533 

A 

405541 .79 

3899489.16 

563 

L 

38599759 

3900572.64 

101 

A 

381782.42 

3905945.17 

501 

A 

39711053 

389825152 

999 
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6.  CONVERTING  DATA  AMONG  VECTOR,  RASTER,  AND  SITES  DATA  FORMATS 

If  you  need  to  convert  data  into  a  specific  file  format,  GRASS  contains  programs  that  will  convert  data 
to  and  from  GRASS  raster,  vector,  and  sites  file  formats.  For  example,  vJo.rast  converts  vector  data  to 
raster  data,  and  vjosites  converts  vector  data  to  sites  data.  The  following  GRASS  programs  are  used  to 
convert  data  among  GRASS  raster,  vector,  and  sites  formats: 


Raster  Data 

Sites  Data 

Vector  Data 

rime 

sinasdi 

v.toxast 

r.pdy 

s  .out  .ascii 

v. to. sites 

r.thin 

v  in  ascii 

r  inascii 
nut  .ascii 
rin-sunrast 
rJnJl 

v. out  ascii 

Other  GRASS  programs  exist  to  convert  data  files  in  GRASS  raster,  vector,  or  sites  formats  to  other 
systems’  data  file  formats,  and  to  bring  data  files  in  other  systems’  formats  into  GRASS’  data  formats. 
For  example,  v  in. arc  can  be  used  to  import  ARC/INFO  data  into  GRASS  vector  formal,  and  v.outMrc 
can  be  used  to  export  GRASS  vector  data  to  ARC/INFO’S  data  file  format. 

7.  GLOSSARY 


Area: 

Area  Edge: 
Attribute: 

Line: 

Line  Segment: 
Map  Feature: 
Node: 

Vector: 


A  closed  polygon,  built  with  one  or  more  Area  Edges. 

A  vector  that  defines  a  portion  erf  an  area  boundary  or  polygon. 

An  integer  number  that  identifies  a  specific  type  of  map  feature.  This  can  be  thought 
of  as  being  equivalent  to  the  category  value  in  die  raster  side  of  GRASS. 

A  vector  that  defines  a  linear  feature  (eg.,  roads). 

A  straight  line  with  two  discrete  end  points. 

A  line  or  area  on  a  map. 

A  discrete  point  where  one  or  more  vectors  end. 

An  element  within  the  digjascii  or  ckgfUe  that  is  defined  as  Point,  Line,  or  Area  Edge 
information  and  consists  of  a  number  of  coordinate  pairs,  which  define  the  number  of 
line  segments. 
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INDEX 


3d.  view. sh 
DOS.delete 
DOS.list 
DOS. save 
DOS. show 
Gen. Maps 
Gen.tractmap 
blend,  sh 
bug.report.sh 
d.3d 

d.6386. delete 
d.6386. save 
d.6386. show 
d.ask 

d. colormode 
d. colors 
d.colortable 
d.display 
d.  erase 
d.font 
d.  frame 
d. geodesic 
d. graph 
d.grid 
d.his 

d. histogram 
d. icons 
d. label 
d. labels 
d. legend 
d.mapgraph 
d.  measure 
d.menu 
d.mon 

d. paint. labels 
d. points 
d. profile 
d.rast 

cl.  rast.  arrow 
d.rast. edit 
d.rast.num 
d.rast. zoom 
d.rgb 

d. rhumbline 

d.save 

d.savcscrecn 
d. scale 
d. sites 
d.text 
d. title 


Format 

Descriptions 


Contributed 

Commands 


page  451 
page  452 
page  453 
page  454 


page  455 
page  456 
page  457 


Shell  Main 

Commands _ Commands 

...  page  429 


page  431 
page  432 
page  433 
page  435 

.  page  13 


page  15 
page  17 
page  19 
page  22 
page  24 
page  26 
page  27 
page  28 
page  29 
page  30 
page  32 
page  33 
page  35 
pa;  e  37 
page  39 
page  41 
page  44 
page  45 
page  47 
page  48 
page  51 
page  53 
page  54 
page  56 
page  58 
page  59 
page  61 
page  64 
page  65 
page  66 
page  67 
page  68 
page  69 
page  70 
page  72 
page  73 
page  75 
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Format 

Descriptions 


Contributed 
Commands 
...  page  458 


Shell 

Commands 


Main 

Commands 


d. to. sites 

d.vect 

d.vect.dlg 

d.what.rast 

d.what.vect 

d.  where 

d.zoom 

dcorrelate.sh 

exit 

g.access 

g.ask 

g.copy 

g. filename 

g.findfile 

g.gisenv 

g.help 

g.list 

g.manual 

g.mapsets 

g.region 

g.  remove 

g.rename 

g.tempfile 

g.version 

grass. logo. sh 

hsv.rgb.sh 

i.build.blk 

i.camera 

i.cca 

i.  class 

i. cluster 

i.  colors 

i. composite 

i.fft 

i.grey. scale 
i. group 
i.his.rgb 
i.ifft 
i.maxlik 
i. median 
i.r.  id. camera 
i.pca 
i. points 
i. rectify 
i.rectify.blk 
i.rgb.his 
i. tape. mss 
i. tape. mss. h 
i. tape. other 
i.tape.tm 
i.  target 
i.zc 
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